@chrisdudek/yg 5.0.0-alpha.3 → 5.0.0-alpha.4

package/dist/bin.js

@@ -162,9 +162,23 @@ var init_graph = __esm({
 });
 
 // src/utils/mapping-path.ts
+import { minimatch } from "minimatch";
 function normalizeMappingPath(p2) {
   return p2.trim().replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
 }
+function isGlobPattern(entry) {
+  return entry.includes("*");
+}
+function globMatch(file, pattern) {
+  return minimatch(file, pattern, { dot: true });
+}
+function mappingEntryMatchesFile(entry, file) {
+  const e = normalizeMappingPath(entry);
+  const f = normalizeMappingPath(file);
+  if (e === "") return false;
+  if (isGlobPattern(e)) return globMatch(f, e);
+  return f === e || f.startsWith(e + "/");
+}
 var init_mapping_path = __esm({
   "src/utils/mapping-path.ts"() {
     "use strict";
@@ -675,6 +689,11 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
   const gitignoreStack = await loadRootGitignoreStack2(projectRoot);
   const allFiles = [];
   for (const tf of trackedFiles) {
+    if (isGlobPattern(tf.path)) {
+      const entries = await expandGlobEntry(projectRoot, tf.path, gitignoreStack);
+      for (const entry of entries) allFiles.push(entry);
+      continue;
+    }
     const absPath = path16.join(projectRoot, tf.path);
     try {
       const st = await stat5(absPath);
@@ -697,7 +716,7 @@ async function hashTrackedFiles(projectRoot, trackedFiles, storedFileData, exclu
       continue;
     }
   }
-  const filtered = excludePrefixes?.length ? allFiles.filter((entry) => !excludePrefixes.some((prefix) => entry.relPath === prefix || entry.relPath.startsWith(prefix + "/"))) : allFiles;
+  const filtered = excludePrefixes?.length ? allFiles.filter((entry) => !excludePrefixes.some((prefix) => mappingEntryMatchesFile(prefix, entry.relPath))) : allFiles;
   const dirty = [];
   for (const entry of filtered) {
     const storedMtime = storedFileData?.mtimes[entry.relPath];
@@ -757,26 +776,50 @@ async function collectDirectoryFilePaths(directoryPath, rootDirectoryPath, optio
   result.push(...fileStats);
   return result;
 }
+async function expandGlobEntry(projectRoot, glob, gitignoreStack) {
+  const segments = glob.split("/");
+  const firstGlobIdx = segments.findIndex((s) => isGlobPattern(s));
+  const baseSegments = firstGlobIdx > 0 ? segments.slice(0, firstGlobIdx) : [];
+  const baseDir = baseSegments.length > 0 ? path16.join(projectRoot, ...baseSegments) : projectRoot;
+  try {
+    const dirEntries = await collectDirectoryFilePaths(baseDir, projectRoot, {
+      projectRoot,
+      gitignoreStack
+    });
+    return dirEntries.filter((entry) => globMatch(entry.relPath, glob)).map((entry) => ({
+      relPath: toPosixPath(entry.relPath),
+      absPath: entry.absPath,
+      mtimeMs: entry.mtimeMs
+    }));
+  } catch {
+    return [];
+  }
+}
 async function expandMappingPaths(projectRoot, mappingPaths) {
   const gitignoreStack = await loadRootGitignoreStack2(projectRoot);
   const result = [];
   for (const mp of mappingPaths) {
-    const absPath = path16.join(projectRoot, mp);
-    try {
-      const st = await stat5(absPath);
-      if (st.isDirectory()) {
-        const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
-          projectRoot,
-          gitignoreStack
-        });
-        for (const entry of dirEntries) {
-          result.push(toPosixPath(path16.join(mp, entry.relPath)));
+    if (isGlobPattern(mp)) {
+      const entries = await expandGlobEntry(projectRoot, mp, gitignoreStack);
+      for (const entry of entries) result.push(entry.relPath);
+    } else {
+      const absPath = path16.join(projectRoot, mp);
+      try {
+        const st = await stat5(absPath);
+        if (st.isDirectory()) {
+          const dirEntries = await collectDirectoryFilePaths(absPath, absPath, {
+            projectRoot,
+            gitignoreStack
+          });
+          for (const entry of dirEntries) {
+            result.push(toPosixPath(path16.join(mp, entry.relPath)));
+          }
+        } else {
+          result.push(toPosixPath(mp));
         }
-      } else {
-        result.push(toPosixPath(mp));
+      } catch {
+        continue;
       }
-    } catch {
-      continue;
     }
   }
   return result;
@@ -786,6 +829,7 @@ var init_hash = __esm({
   "src/io/hash.ts"() {
     "use strict";
     init_posix();
+    init_mapping_path();
     init_repo_scanner();
     require3 = createRequire2(import.meta.url);
     ignoreFactory2 = require3("ignore");
@@ -1047,10 +1091,10 @@ function computeEffectiveAspectStatuses(node, graph) {
   for (const a of graph.aspects) idToAspect.set(a.id, a);
   let changed = true;
   let iterations = 0;
-  const maxIterations = graph.aspects.length + 1;
+  const maxIterations = graph.aspects.length + 2;
   while (changed) {
     if (++iterations > maxIterations) {
-      throw new ImpliesCycleError(`implies fix-point did not converge after ${maxIterations} iterations (cycle suspected)`);
+      throw new ImpliesCycleError("implies fix-point exceeded its iteration bound (internal invariant violated)");
     }
     changed = false;
     const currentIds = [...result.keys()];
@@ -1258,8 +1302,7 @@ function collectTrackedFiles(node, graph, baseline) {
   }
   const allAspectIds = computeEffectiveAspects(node, graph);
   const mappingPathsList = normalizeMappingPaths(node.meta.mapping);
-  const mappingPathsSet = new Set(mappingPathsList);
-  const isOwnedByMapping = (p2) => mappingPathsSet.has(p2) || mappingPathsList.some((m) => p2.startsWith(m + "/"));
+  const isOwnedByMapping = (p2) => mappingPathsList.some((m) => mappingEntryMatchesFile(m, p2));
   for (const aspectId of allAspectIds) {
     const aspect = graph.aspects.find((a) => a.id === aspectId);
     if (!aspect) continue;
@@ -1363,6 +1406,7 @@ var init_files = __esm({
   "src/core/graph/files.ts"() {
     "use strict";
     init_paths();
+    init_mapping_path();
     init_traversal();
     init_aspects();
     init_tier_selection();
@@ -3106,9 +3150,8 @@ function isAllowed(p2, set) {
   if (p2 === "") return false;
   if (set.has(p2)) return true;
   for (const a of set) {
-    if (a === p2) return true;
     if (a.startsWith(p2 + "/")) return true;
-    if (p2.startsWith(a + "/")) return true;
+    if (mappingEntryMatchesFile(a, p2)) return true;
   }
   return false;
 }
@@ -3200,13 +3243,7 @@ var init_ctx_fs = __esm({
 function isPathInMapping(candidate, mapping) {
   const c = normalizeMappingPath(candidate);
   if (c === "") return false;
-  for (const raw of mapping) {
-    const n = normalizeMappingPath(raw);
-    if (n === "") continue;
-    if (c === n) return true;
-    if (c.startsWith(n + "/")) return true;
-  }
-  return false;
+  return mapping.some((raw) => mappingEntryMatchesFile(raw, c));
 }
 var init_expand_mapping_sync = __esm({
   "src/structure/expand-mapping-sync.ts"() {
@@ -3247,15 +3284,16 @@ function computeAllowedNodePaths(currentPath, graph) {
   return allowed;
 }
 function createCtxGraph(params) {
-  const { currentNodePath, graph, projectRoot, touchedFiles } = params;
+  const { currentNodePath, graph, projectRoot, touchedFiles, expandedFilesByNode } = params;
   const allowed = computeAllowedNodePaths(currentNodePath, graph);
   function assertAllowed(id) {
     if (!allowed.has(id)) throw new UndeclaredGraphReadError(id);
   }
   function toPublicNode(m) {
     const files = [];
-    for (const raw of m.meta.mapping ?? []) {
-      const p2 = normalizeMappingPath(raw);
+    const preExpanded = expandedFilesByNode?.get(m.path);
+    const candidatePaths = preExpanded ?? (m.meta.mapping ?? []).map(normalizeMappingPath);
+    for (const p2 of candidatePaths) {
       if (!p2) continue;
       const abs = path29.resolve(projectRoot, p2);
       try {
@@ -3354,10 +3392,14 @@ import path30 from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { existsSync as existsSync5 } from "fs";
 import { createRequire as createRequire3 } from "module";
-async function init() {
-  if (initialized) return;
-  await Parser.init();
-  initialized = true;
+function init() {
+  if (initPromise === null) {
+    initPromise = Parser.init();
+    initPromise.catch(() => {
+      initPromise = null;
+    });
+  }
+  return initPromise;
 }
 function resolveWasm(filename, pkg2) {
   for (const dir of GRAMMAR_DIRS) {
@@ -3380,12 +3422,16 @@ async function getParser(extension) {
     throw new Error(`no parser for extension '${extension}'`);
   }
   const cacheKey = info.wasmFile;
-  let lang = langCache.get(cacheKey);
-  if (!lang) {
+  let langP = langCache.get(cacheKey);
+  if (langP === void 0) {
     const wasmPath = resolveWasm(info.wasmFile, info.wasmPackage);
-    lang = await Language.load(wasmPath);
-    langCache.set(cacheKey, lang);
+    langP = Language.load(wasmPath);
+    langCache.set(cacheKey, langP);
+    langP.catch(() => {
+      if (langCache.get(cacheKey) === langP) langCache.delete(cacheKey);
+    });
   }
+  const lang = await langP;
   const parser = new Parser();
   parser.setLanguage(lang);
   return parser;
@@ -3399,7 +3445,7 @@ async function parseFile(filePath, content14) {
   }
   return tree;
 }
-var _require, __filename2, __dirname2, GRAMMAR_DIRS, initialized, langCache;
+var _require, __filename2, __dirname2, GRAMMAR_DIRS, initPromise, langCache;
 var init_parser = __esm({
   "src/ast/parser.ts"() {
     "use strict";
@@ -3411,7 +3457,7 @@ var init_parser = __esm({
       path30.resolve(__dirname2, "grammars"),
       path30.resolve(__dirname2, "..", "grammars")
     ];
-    initialized = false;
+    initPromise = null;
     langCache = /* @__PURE__ */ new Map();
   }
 });
@@ -3640,15 +3686,23 @@ function parseMarker(commentText, line, file) {
   if (m) return makeMarker("single", m, line, file);
   return null;
 }
-function collectSuppressions(tree, file, totalLines) {
-  if (getLanguageForExtension(extname3(file)) === null) {
-    return [];
-  }
-  const comments = findComments({ path: file, ast: tree });
+function collectSuppressions(tree, file, totalLines, content14) {
+  const hasGrammar = getLanguageForExtension(extname3(file)) !== null;
   const markers = [];
-  for (const c of comments) {
-    const m = parseMarker(c.text, c.startPosition.row + 1, file);
-    if (m) markers.push(m);
+  if (hasGrammar && tree) {
+    const comments = findComments({ path: file, ast: tree });
+    for (const c of comments) {
+      const m = parseMarker(c.text, c.startPosition.row + 1, file);
+      if (m) markers.push(m);
+    }
+  } else if (content14 !== void 0) {
+    const lines = content14.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = parseMarker(lines[i], i + 1, file);
+      if (m) markers.push(m);
+    }
+  } else {
+    return [];
   }
   markers.sort((a, b) => a.line - b.line);
   const ranges = [];
@@ -3746,8 +3800,8 @@ var init_suppress = __esm({
       }
       code = "SUPPRESS_MARKER_MISSING_REASON";
     };
-    RE_SINGLE = /\byg-suppress\(\s*([^)]+?)\s*\)\s*(.+)?$/;
-    RE_DISABLE = /\byg-suppress-disable\(\s*([^)]+?)\s*\)\s*(.+)?$/;
+    RE_SINGLE = /\byg-suppress\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
+    RE_DISABLE = /\byg-suppress-disable\(\s*([^)]+?)\s*\)\s*(.+)?$/m;
     RE_ENABLE = /\byg-suppress-enable\(\s*([^)]+?)\s*\)/;
   }
 });
@@ -3878,7 +3932,12 @@ async function runStructureAspect(params) {
   const checkFn = mod.check;
   const allowedSet = collectAllowedReadsForAspect(nodePath, graph);
   const ctxFs = createCtxFs({ allowedSet, projectRoot, touchedFiles });
-  const ctxGraph = createCtxGraph({ currentNodePath: nodePath, graph, projectRoot, touchedFiles });
+  const expandedFilesByNode = /* @__PURE__ */ new Map();
+  for (const id of computeAllowedNodePaths(nodePath, graph)) {
+    const m = graph.nodes.get(id);
+    if (m) expandedFilesByNode.set(id, await enumerateMappedFilesAsync(m.meta.mapping ?? [], projectRoot));
+  }
+  const ctxGraph = createCtxGraph({ currentNodePath: nodePath, graph, projectRoot, touchedFiles, expandedFilesByNode });
   const parsers = createCtxParsers({ allowedSet, projectRoot, touchedFiles, astCache });
   const ownFiles = await buildOwnFiles(node, projectRoot, touchedFiles);
   await prewarmupAstCache({ astCache, projectRoot, files: ownFiles });
@@ -3992,12 +4051,22 @@ ${err.stack ?? ""}`,
     }
     violations.push(vv);
   }
+  const contentByPath = /* @__PURE__ */ new Map();
+  for (const f of [...ownFiles, ...astInputSet]) {
+    contentByPath.set(normalizeMappingPath(f.path), f.content);
+  }
   const rangesByFile = /* @__PURE__ */ new Map();
   function rangesFor(filePath) {
     const existing = rangesByFile.get(filePath);
     if (existing !== void 0) return existing;
     const cached = astCache.get(filePath);
-    const ranges = cached ? collectSuppressions(cached.ast, filePath, cached.content.split("\n").length) : null;
+    let ranges;
+    if (cached) {
+      ranges = collectSuppressions(cached.ast, filePath, cached.content.split("\n").length, cached.content);
+    } else {
+      const content14 = contentByPath.get(filePath);
+      ranges = content14 !== void 0 ? collectSuppressions(void 0, filePath, content14.split("\n").length, content14) : null;
+    }
     rangesByFile.set(filePath, ranges);
     return ranges;
   }
@@ -4591,7 +4660,7 @@ The CLI (\`yg\`) reads and validates \u2014 it never modifies files. You create
   .drift-state/        \u2190 generated by CLI; never edit manually
 \`\`\`
 
-**Nodes** \u2014 components. \`model/<path>/yg-node.yaml\`. Nodes nest by directory \u2014 children inherit parent aspects. Schema: \`schemas/yg-node.yaml\`.
+**Nodes** \u2014 components. \`model/<path>/yg-node.yaml\`. Nodes nest by directory \u2014 children inherit parent aspects. Schema: \`schemas/yg-node.yaml\`. Node \`mapping:\` entries and architecture \`when.path\` both accept minimatch glob patterns \u2014 \`*\` matches within a single path segment, \`**\` matches across segments (e.g. \`src/db/*Repository.cs\` maps only repository files in that directory; \`src/**/*.ts\` maps all TypeScript files under src).
 
 **Aspects** \u2014 enforceable rules. \`aspects/<id>/yg-aspect.yaml\` + zero or one rule source files. The reviewer kind is inferred from which rule source is present: \`content.md\` \u2192 LLM reviewer; \`check.mjs\` \u2192 deterministic reviewer; neither file but \`implies:\` declared \u2192 aggregating aspect (a named bundle with no own reviewer). The \`reviewer:\` block in \`yg-aspect.yaml\` is optional \u2014 kind is inferred automatically. If present, an explicit \`reviewer.type\` must agree with the inferred kind. LLM aspects may set \`reviewer.tier:\` to pick a named tier from \`yg-config.yaml\` (otherwise the configured default tier is used). An aspect can declare \`implies: [other-aspect]\` \u2014 implied aspects are included recursively (must be acyclic). LLM aspects may declare \`references:\` \u2014 supporting files (lookup tables, catalogues) included in the reviewer prompt and exposed to the agent under \`read:\`. Schema: \`schemas/yg-aspect.yaml\`. Aspects also carry a \`status:\` field (default \`enforced\`) \u2014 three levels \`draft / advisory / enforced\` control whether the reviewer runs and whether violations block.
 
@@ -4984,7 +5053,7 @@ context.
 
 **Flow** \u2014 when you see a sequence of steps toward a business goal. Not code call sequences \u2014 real-world processes. "User places an order" = flow. "Handler calls service" = relation between nodes. Read \`schemas/yg-flow.yaml\` and \`yg knowledge read flows\` before creating.
 
-**Node** \u2014 one per cohesive feature area. Not per directory, not per file. If a node's mapped source (plus any aspect reference files) exceeds the per-node character budget (\`quality.max_node_chars\`, default 40000) or it covers >3 distinct workflows, split into children \u2014 \`yg check\` enforces the budget as an \`oversized-node\` error. Why: the reviewer sees ALL files in a node at once; an oversized context dilutes focus and risks window truncation that falsely rejects unchanged code. Keep each node well under the budget. Binary files (images, fonts, archives, etc.) count 0 toward the budget automatically. A node mapping a single unsplittable generated **text** artifact (e.g. a large lockfile) can opt out with \`sizeExempt: { reason: "..." }\`. Read \`schemas/yg-node.yaml\` before creating.
+**Node** \u2014 one per cohesive feature area. Not per directory, not per file. If a node's mapped source (plus any aspect reference files) exceeds the per-node character budget (\`quality.max_node_chars\`, default 40000) or it covers >3 distinct workflows, split into children \u2014 \`yg check\` enforces the budget as an \`oversized-node\` error. Why: the LLM reviewer sends ALL of a node's files in one prompt, so an oversized context dilutes focus and risks window truncation that falsely rejects unchanged code. The budget therefore applies ONLY to nodes an LLM reviewer actually reads \u2014 those with at least one non-draft LLM aspect; deterministic-only and aspect-less nodes carry no budget (a \`check.mjs\` reads files programmatically, with no context window). Keep LLM-reviewed nodes well under the budget. Binary files (images, fonts, archives, etc.) count 0 toward the budget automatically. A node mapping a single unsplittable generated **text** artifact (e.g. a large lockfile) can opt out with \`sizeExempt: { reason: "..." }\`. Read \`schemas/yg-node.yaml\` before creating.
 
 **Port / relation** \u2014 when a critical aspect must cross a node boundary, or when a new typed dependency is needed. Bare relations do NOT propagate aspects; ports do. Six relation types exist (\`calls\`, \`uses\`, \`extends\`, \`implements\`, \`emits\`, \`listens\`); event relations must be paired. Deep dive: \`yg knowledge read ports-and-relations\`.
 
@@ -5719,13 +5788,6 @@ function parseCoverage(raw, filename) {
   const cov = raw;
   const required = cov.required === void 0 ? ["/"] : parseStringArray(cov.required, "coverage.required", filename);
   const excluded = parseStringArray(cov.excluded, "coverage.excluded", filename);
-  if (required.length === 0) {
-    throw new ConfigParseError({
-      what: `${filename}: coverage.required must list at least one root.`,
-      why: "An empty required list silently turns every unmapped file into a non-blocking warning, disabling coverage enforcement.",
-      next: "Omit the coverage block to require the whole repo, or list real roots (e.g. - services/)."
-    }, "config-invalid");
-  }
   for (const root of [...required, ...excluded]) {
     if (root.split("/").includes("..")) {
       throw new ConfigParseError({
@@ -5748,6 +5810,17 @@ function parseMaxNodeChars(raw, filename) {
   }
   return raw;
 }
+function parseMaxDirectRelations(raw, filename) {
+  if (raw === void 0) return DEFAULT_QUALITY.max_direct_relations ?? 10;
+  if (typeof raw !== "number" || !Number.isInteger(raw) || raw <= 0) {
+    throw new ConfigParseError({
+      what: `${filename}: quality.max_direct_relations must be a positive integer (got ${JSON.stringify(raw)}).`,
+      why: "It is the per-node relation-count budget; a zero, negative, or fractional value makes the threshold nonsensical.",
+      next: "Set quality.max_direct_relations to a positive integer (default 10), or remove it to use the default."
+    }, "config-invalid");
+  }
+  return raw;
+}
 var PROVIDER_DEFAULTS = {
   "claude-code": { model: "haiku" },
   "codex": { model: "o4-mini" },
@@ -5775,7 +5848,7 @@ async function parseConfig(filePath) {
   }
   const qualityMap = qualityRaw;
   const quality = qualityMap ? {
-    max_direct_relations: typeof qualityMap.max_direct_relations === "number" ? qualityMap.max_direct_relations : DEFAULT_QUALITY.max_direct_relations,
+    max_direct_relations: parseMaxDirectRelations(qualityMap.max_direct_relations, filename),
     max_node_chars: parseMaxNodeChars(qualityMap.max_node_chars, filename)
   } : DEFAULT_QUALITY;
   let reviewer;
@@ -5952,6 +6025,13 @@ function parseTier(name, raw, filename) {
       next: "add `model: <model-name>` under config:"
     }, "config-tier-config-missing");
   }
+  if (t.provider === "openai-compatible" && (typeof c.endpoint !== "string" || !c.endpoint.trim())) {
+    throw new ConfigParseError({
+      what: `${filename}: tier '${name}' (provider 'openai-compatible') is missing config.endpoint`,
+      why: `'openai-compatible' has no default host \u2014 without an explicit endpoint it silently falls back to the public OpenAI API (api.openai.com).`,
+      next: "add `endpoint: <url>` under config: pointing at your compatible server."
+    }, "config-tier-endpoint-missing");
+  }
   const allowed = /* @__PURE__ */ new Set(["provider", "consensus", "config", "references"]);
   for (const k of Object.keys(t)) {
     if (!allowed.has(k)) {
@@ -6375,6 +6455,10 @@ function parseRelations(raw, filePath) {
         );
       }
       rel.consumes = consumesArr;
+    } else if (obj.consumes !== void 0) {
+      throw new Error(
+        `yg-node.yaml at ${filePath}: relations[${index}].consumes must be an array of string port names (got ${Array.isArray(obj.consumes) ? "array" : typeof obj.consumes}). A scalar value is silently ignored, so the consumed port's required aspects would not be enforced. Use consumes: [<port-name>].`
+      );
     }
     if (typeof obj.event_name === "string" && obj.event_name.trim()) {
       rel.event_name = obj.event_name.trim();
@@ -6933,13 +7017,13 @@ function parseReviewer2(raw, aspectId, files) {
         next: "add `type: llm` or `type: deterministic` under reviewer:"
       }
     });
-  } else if (obj.type !== "llm" && obj.type !== "deterministic") {
+  } else if (obj.type !== "llm" && obj.type !== "deterministic" && obj.type !== "aggregate") {
     errors.push({
       code: "aspect-reviewer-type-invalid",
       messageData: {
         what: `aspect '${aspectId}' has invalid reviewer.type: '${String(obj.type)}'`,
-        why: 'only "llm" and "deterministic" are valid',
-        next: "change to type: llm or type: deterministic"
+        why: 'only "llm", "deterministic", or "aggregate" are valid',
+        next: "change to type: llm, type: deterministic, or type: aggregate"
       }
     });
   } else {
@@ -9427,7 +9511,7 @@ init_posix();
 import path21 from "path";
 
 // src/core/file-when-evaluator.ts
-import { minimatch } from "minimatch";
+init_mapping_path();
 var YGGDRASIL_PREFIX = ".yggdrasil/";
 function safeRegexTest(re, str) {
   const HEAD_LIMIT = 256 * 1024;
@@ -9506,7 +9590,7 @@ async function evaluateAtomic2(predicate, ctx) {
     );
   }
   if (predicate.path !== void 0) {
-    const matches = minimatch(ctx.repoRelPath, predicate.path, { dot: true });
+    const matches = globMatch(ctx.repoRelPath, predicate.path);
     return {
       result: matches,
       trace: { kind: "atom-path", pattern: predicate.path, result: matches }
@@ -9549,7 +9633,15 @@ async function evaluateAtomic2(predicate, ctx) {
         }
       };
     }
-    const regex = new RegExp(predicate.content);
+    let regex;
+    try {
+      regex = new RegExp(predicate.content);
+    } catch {
+      return {
+        result: false,
+        trace: { kind: "atom-content", pattern: predicate.content, result: false, detail: "invalid content regex" }
+      };
+    }
     const { match: matches } = safeRegexTest(regex, fileContent.content);
     return {
       result: matches,
@@ -9610,6 +9702,9 @@ function renderNode(node, indent, lines) {
 }
 
 // src/core/checks/architecture.ts
+init_hash();
+init_mapping_path();
+init_posix();
 function checkTypeUnknownParent(graph) {
   const issues = [];
   const knownTypes = new Set(Object.keys(graph.architecture.node_types));
@@ -9767,7 +9862,15 @@ async function checkTypeWhenMismatch(graph, cache) {
     const typeDef = graph.architecture.node_types[node.meta.type];
     if (typeDef === void 0 || typeDef.when === void 0) continue;
     const mapping = node.meta.mapping ?? [];
-    for (const relPath of mapping) {
+    const pathsToCheck = [];
+    for (const entry of mapping) {
+      if (isGlobPattern(entry)) {
+        pathsToCheck.push(...(await expandMappingPaths(projectRoot, [entry])).map(toPosixPath));
+      } else {
+        pathsToCheck.push(entry);
+      }
+    }
+    for (const relPath of pathsToCheck) {
       const absPath = path21.join(projectRoot, relPath);
       const result = await evaluateFileWhen(typeDef.when, {
         absPath,
@@ -10266,6 +10369,23 @@ function checkWhenReferences(graph) {
             })
           });
         }
+      } else if (match.consumes_port !== void 0) {
+        const port = match.consumes_port;
+        const known = [...graph.nodes.values()].some(
+          (n) => n.meta.ports !== void 0 && port in n.meta.ports
+        );
+        if (!known) {
+          issues.push({
+            severity: "error",
+            code: "when-unknown-port",
+            rule: "when-unknown-port",
+            ...issueMsg({
+              what: `Port '${port}' in when at ${ctx}/${relType}.consumes_port is not declared on any node.`,
+              why: "The predicate references a port that no node defines, so it can never match.",
+              next: `Fix the port name, or declare it under ports: on the node(s) this relation targets.`
+            })
+          });
+        }
       }
     }
   };
@@ -10657,7 +10777,7 @@ function checkAspectStatusDowngrade(graph) {
       for (const source of sources) {
         if (!sourceIsExplicit(source, node, aspectId, graph)) continue;
         const otherDeclared = sources.filter((s) => s !== source).map((s) => s.declared);
-        const anchor = otherDeclared.length === 0 ? aspectDefault : otherDeclared.reduce(
+        const anchor = [...otherDeclared, aspectDefault].reduce(
           (acc, cur) => STATUS_ORDER[cur] > STATUS_ORDER[acc] ? cur : acc,
           "draft"
         );
@@ -10687,6 +10807,7 @@ function checkAspectStatusDowngrade(graph) {
 // src/core/checks/mapping.ts
 init_paths();
 init_hash();
+init_mapping_path();
 init_graph_fs();
 init_repo_scanner();
 init_aspects();
@@ -10734,12 +10855,6 @@ async function checkStrictBackwardCoverage(graph, cache) {
   );
   if (strictTypes.length === 0) return { issues: [], unreadable: [] };
   const projectRoot = path23.dirname(graph.rootPath);
-  const fileToOwner = /* @__PURE__ */ new Map();
-  for (const [nodePath, node] of graph.nodes) {
-    for (const relPath of node.meta.mapping ?? []) {
-      if (!fileToOwner.has(relPath)) fileToOwner.set(relPath, { nodePath, nodeType: node.meta.type });
-    }
-  }
   const repoFiles = await walkRepoFiles(projectRoot);
   const issues = [];
   const unreadable = [];
@@ -10802,7 +10917,14 @@ Run: yg impact --type ${sorted[j]}`
     }
     if (matchingTypes.length === 0) continue;
     const { typeId, trace } = matchingTypes[0];
-    const owner = fileToOwner.get(relPath);
+    let owner;
+    for (const [nodePath, node] of graph.nodes) {
+      const entries = node.meta.mapping ?? [];
+      if (entries.some((entry) => mappingEntryMatchesFile(entry, relPath))) {
+        owner = { nodePath, nodeType: node.meta.type };
+        break;
+      }
+    }
     if (owner === void 0) {
       issues.push({
         severity: "error",
@@ -10847,7 +10969,7 @@ function arePathsOverlapping(pathA, pathB) {
 function isAncestorNode(possibleAncestor, possibleDescendant) {
   return possibleDescendant.startsWith(possibleAncestor + "/");
 }
-function checkMappingOverlap(graph) {
+async function checkMappingOverlap(graph) {
   const issues = [];
   const ownership = [];
   for (const [nodePath, node] of graph.nodes) {
@@ -10893,6 +11015,46 @@ function checkMappingOverlap(graph) {
       });
     }
   }
+  const anyGlob = [...graph.nodes.values()].some(
+    (n) => (n.meta.mapping ?? []).some((e) => isGlobPattern(e))
+  );
+  if (anyGlob) {
+    const projectRoot = path23.dirname(graph.rootPath);
+    const repoFiles = await walkRepoFiles(projectRoot);
+    const reported = /* @__PURE__ */ new Set();
+    for (const rawRel of repoFiles) {
+      const relPath = normalizePathForCompare(rawRel);
+      const owners = [];
+      let viaGlob = false;
+      for (const [nodePath, node] of graph.nodes) {
+        let matched = false;
+        for (const entry of node.meta.mapping ?? []) {
+          if (!mappingEntryMatchesFile(entry, relPath)) continue;
+          matched = true;
+          if (isGlobPattern(entry)) viaGlob = true;
+        }
+        if (matched) owners.push(nodePath);
+      }
+      if (owners.length < 2 || !viaGlob || reported.has(relPath)) continue;
+      const leaves = owners.filter(
+        (o) => !owners.some((other) => other !== o && isAncestorNode(o, other))
+      );
+      if (leaves.length < 2) continue;
+      reported.add(relPath);
+      issues.push({
+        severity: "error",
+        code: "overlapping-mapping",
+        rule: "overlapping-mapping",
+        ...issueMsg({
+          what: `File '${relPath}' is owned by multiple non-hierarchical nodes:
+${leaves.map((n) => "  " + n).join("\n")}`,
+          why: `Each source file must have exactly one owner node. A glob mapping in one node resolves to a file also claimed by another node.`,
+          next: `Narrow the glob, or remove the file from one node's mapping and model the dependency via a relation.`
+        }),
+        nodePath: leaves[0]
+      });
+    }
+  }
   return issues;
 }
 async function checkMappingPathsExist(graph) {
@@ -10901,21 +11063,38 @@ async function checkMappingPathsExist(graph) {
   for (const [nodePath, node] of graph.nodes) {
     const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizePathForCompare);
     for (const mp of mappingPaths) {
-      const absPath = path23.join(projectRoot, mp);
-      try {
-        await fileAccess(absPath);
-      } catch {
-        issues.push({
-          severity: "error",
-          code: "mapping-path-missing",
-          rule: "mapping-path-missing",
-          ...issueMsg({
-            what: `Mapping path '${mp}' does not exist on disk.`,
-            why: `Node maps a file that was deleted or moved.`,
-            next: `Update mapping in yg-node.yaml: fix the path or remove the entry.`
-          }),
-          nodePath
-        });
+      if (isGlobPattern(mp)) {
+        const matched = await expandMappingPaths(projectRoot, [mp]);
+        if (matched.length === 0) {
+          issues.push({
+            severity: "error",
+            code: "mapping-path-missing",
+            rule: "mapping-path-missing",
+            ...issueMsg({
+              what: `Glob '${mp}' matches no files on disk.`,
+              why: `Node maps a glob pattern that currently resolves to no files \u2014 possibly all matching files were deleted or the pattern is wrong.`,
+              next: `Update mapping in yg-node.yaml: fix the glob or remove the entry.`
+            }),
+            nodePath
+          });
+        }
+      } else {
+        const absPath = path23.join(projectRoot, mp);
+        try {
+          await fileAccess(absPath);
+        } catch {
+          issues.push({
+            severity: "error",
+            code: "mapping-path-missing",
+            rule: "mapping-path-missing",
+            ...issueMsg({
+              what: `Mapping path '${mp}' does not exist on disk.`,
+              why: `Node maps a file that was deleted or moved.`,
+              next: `Update mapping in yg-node.yaml: fix the path or remove the entry.`
+            }),
+            nodePath
+          });
+        }
       }
     }
   }
@@ -10985,6 +11164,7 @@ async function checkOversizedNodes(graph, cache) {
       refsByAspect.set(aspect.id, aspect.references.map((r) => r.path));
     }
   }
+  const aspectById = new Map(graph.aspects.map((a) => [a.id, a]));
   async function charsOf(repoRelPath) {
     if (BINARY_EXTENSIONS.has(path23.extname(repoRelPath).toLowerCase())) return 0;
     const abs = path23.resolve(projectRoot, repoRelPath);
@@ -11004,13 +11184,24 @@ async function checkOversizedNodes(graph, cache) {
     const mappingPaths = normalizeMappingPaths(node.meta.mapping);
     if (mappingPaths.length === 0) continue;
     const sourceFiles = await expandMappingPaths(projectRoot, mappingPaths);
-    const refPaths = /* @__PURE__ */ new Set();
     let effectiveAspects;
     try {
       effectiveAspects = computeEffectiveAspects(node, graph);
     } catch {
       effectiveAspects = /* @__PURE__ */ new Set();
     }
+    let statuses;
+    try {
+      statuses = computeEffectiveAspectStatuses(node, graph);
+    } catch {
+      statuses = /* @__PURE__ */ new Map();
+    }
+    const isLlmReviewed = [...effectiveAspects].some((id) => {
+      const def = aspectById.get(id);
+      return def?.reviewer.type === "llm" && (statuses.get(id) ?? "enforced") !== "draft";
+    });
+    if (!isLlmReviewed) continue;
+    const refPaths = /* @__PURE__ */ new Set();
     for (const aspectId of effectiveAspects) {
       for (const rp of refsByAspect.get(aspectId) ?? []) refPaths.add(rp);
     }
@@ -11448,7 +11639,7 @@ async function validate(graph, scope = "all") {
   issues.push(...checkSchemas(graph));
   issues.push(...checkRelationTargets(graph));
   issues.push(...checkNoCycles(graph));
-  issues.push(...checkMappingOverlap(graph));
+  issues.push(...await checkMappingOverlap(graph));
   issues.push(...checkMappingEscapesRepo(graph));
   issues.push(...await checkMappingPathsExist(graph));
   issues.push(...checkBrokenFlowRefs(graph));
@@ -11520,6 +11711,7 @@ init_debug_log();
 init_message_builder();
 init_paths();
 init_posix();
+init_mapping_path();
 function normalizeForMatch(inputPath) {
   return toPosixPath(inputPath.trim());
 }
@@ -11529,17 +11721,25 @@ function findOwner(graph, projectRoot, rawPath) {
   for (const [nodePath, node] of graph.nodes) {
     const mappingPaths = normalizeMappingPaths(node.meta.mapping).map(normalizeForMatch).filter((mappingPath) => mappingPath.length > 0);
     for (const mappingPath of mappingPaths) {
-      if (file === mappingPath) {
-        return { file, nodePath, mappingPath, direct: true };
-      }
-      if (file.startsWith(mappingPath + "/")) {
-        if (!best || best && mappingPath.length > best.mappingPath.length) {
-          best = { nodePath, mappingPath, exact: false };
+      if (isGlobPattern(mappingPath)) {
+        if (mappingEntryMatchesFile(mappingPath, file)) {
+          if (!best || mappingPath.length > best.mappingPath.length) {
+            best = { nodePath, mappingPath, exact: true };
+          }
+        }
+      } else {
+        if (file === mappingPath) {
+          return { file, nodePath, mappingPath, direct: true };
+        }
+        if (file.startsWith(mappingPath + "/")) {
+          if (!best || mappingPath.length > best.mappingPath.length) {
+            best = { nodePath, mappingPath, exact: false };
+          }
         }
       }
     }
   }
-  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath, direct: false } : { file, nodePath: null };
+  return best ? { file, nodePath: best.nodePath, mappingPath: best.mappingPath, direct: best.exact } : { file, nodePath: null };
 }
 function registerOwnerCommand(program2) {
   program2.command("owner").description("Find which graph node owns a source file").requiredOption("--file <path>", "File path (relative to repository root)").action(async (options) => {
@@ -11559,11 +11759,21 @@ function registerOwnerCommand(program2) {
           exists = false;
         }
         if (exists) {
-          process.stdout.write(`${result.file} -> no graph coverage
-`);
+          process.stdout.write(
+            buildIssueMessage({
+              what: `${result.file} -> no graph coverage`,
+              why: "This file exists but no graph node maps it, so its code is not verified against any aspect.",
+              next: `Add '${result.file}' to a node's mapping in yg-node.yaml, or create a node for it.`
+            }) + "\n"
+          );
         } else {
-          process.stdout.write(`${result.file} -> no graph coverage (file not found)
-`);
+          process.stdout.write(
+            buildIssueMessage({
+              what: `${result.file} -> no graph coverage (file not found)`,
+              why: "This path does not exist on disk and is not mapped by any graph node.",
+              next: `Check the path for typos; once the file exists, add it to a node's mapping in yg-node.yaml.`
+            }) + "\n"
+          );
         }
       } else {
         process.stdout.write(`${result.file} -> ${result.nodePath}
@@ -11791,6 +12001,13 @@ var STRUCTURAL_CODES = /* @__PURE__ */ new Set([
   "when-unknown-type",
   "when-unknown-node",
   "when-unknown-port",
+  // Port-contract codes — blocking architecture-gate errors (documented in the
+  // ports-and-relations knowledge topic); belong in the single-source structural set.
+  "port-missing-consumes",
+  "port-undefined",
+  "port-missing-aspect",
+  "consumes-without-ports",
+  "relation-target-forbidden",
   "aspect-unexpected-rule-source",
   "aspect-missing-rule-source",
   "aspect-empty",
@@ -11819,14 +12036,16 @@ var COMPLETENESS_CODES = /* @__PURE__ */ new Set(["description-missing"]);
 init_log_format();
 init_posix();
 init_repo_scanner();
+init_mapping_path();
 
 // src/core/check-coverage-tiers.ts
 init_posix();
+init_mapping_path();
 function normalizeRoot(root) {
   return toPosixPath(root.trim()).replace(/^\/+/, "").replace(/\/+$/, "").replace(/\/{2,}/g, "/");
 }
 function matchesRoot(file, normRoot) {
-  return normRoot === "" || file === normRoot || file.startsWith(normRoot + "/");
+  return normRoot === "" || mappingEntryMatchesFile(normRoot, file);
 }
 function partitionByCoverageTier(uncovered, coverage) {
   const req = coverage.required.map(normalizeRoot);
@@ -12159,14 +12378,7 @@ function scanUncoveredFiles(graph, gitTrackedFiles) {
   for (const file of tracked) {
     const normalized = toPosixPath(file.trim());
     if (normalized.startsWith(yggPrefix + "/") || normalized === yggPrefix) continue;
-    let covered = false;
-    for (const rawMp of allMappings) {
-      const mp = toPosixPath(rawMp);
-      if (normalized === mp || normalized.startsWith(mp + "/")) {
-        covered = true;
-        break;
-      }
-    }
+    const covered = allMappings.some((mp) => mappingEntryMatchesFile(mp, normalized));
     if (!covered) {
       uncovered.push(normalized);
     }
@@ -12332,10 +12544,15 @@ function getChildMappingExclusions2(graph, nodePath) {
 }
 async function allPathsMissing(projectRoot, mappingPaths) {
   for (const mp of mappingPaths) {
-    try {
-      await fileAccess(path34.join(projectRoot, mp));
-      return false;
-    } catch {
+    if (isGlobPattern(mp)) {
+      const matched = await expandMappingPaths(projectRoot, [mp]);
+      if (matched.length > 0) return false;
+    } else {
+      try {
+        await fileAccess(path34.join(projectRoot, mp));
+        return false;
+      } catch {
+      }
     }
   }
   return true;
@@ -12444,7 +12661,7 @@ function computeSuggestedNext(issues, graph) {
     addRemaining(coverageErrors.length > 0 ? coverageErrors[0].uncoveredCount ?? 0 : 0, "files need coverage");
     const then = remaining.length > 0 ? `
   Then: ${remaining.join(", ")}` : "";
-    return `Fix ${first.code} in ${first.nodePath ?? ".yggdrasil/"}
+    return `Fix ${first.code} in ${first.nodePath ?? ".yggdrasil"}
   1 of ${structuralErrors.length} structural error${structuralErrors.length === 1 ? "" : "s"}${then}`;
   }
   if (coverageErrors.length > 0) {
@@ -14249,6 +14466,7 @@ init_loader_hook();
 init_parser();
 init_suppress();
 init_validate_check_module();
+init_language_registry();
 import path37 from "path";
 import { readFile as readFile20 } from "fs/promises";
 import { pathToFileURL as pathToFileURL3 } from "url";
@@ -14296,18 +14514,15 @@ async function runAstAspect(params) {
       continue;
     }
     const content14 = await readFile20(path37.resolve(params.projectRoot, f.path), "utf-8");
+    if (getLanguageForExtension(path37.extname(f.path).toLowerCase()) === null) {
+      sourceFiles.push({ path: f.path, content: content14, ast: void 0 });
+      continue;
+    }
     let ast;
     try {
       ast = await parseFile(f.path, content14);
     } catch (e) {
       const msg = e.message ?? String(e);
-      if (msg.startsWith("no parser for extension")) {
-        throw new AstRunnerError("AST_NO_PARSER_FOR_EXTENSION", {
-          what: msg + ` (file: ${f.path})`,
-          why: `v1 supports only .ts/.tsx/.js/.mjs/.cjs/.jsx.`,
-          next: `Remove ${f.path} from the node's mapping.`
-        });
-      }
       throw new AstRunnerError("AST_GRAMMAR_LOAD_FAILED", {
         what: `Failed to load tree-sitter grammar for ${f.path}: ${msg}`,
         why: `The bundled WASM grammar could not be loaded.`,
@@ -14328,7 +14543,7 @@ async function runAstAspect(params) {
   const rangesPerFile = /* @__PURE__ */ new Map();
   for (const f of sourceFiles) {
     const totalLines = f.content.split("\n").length;
-    rangesPerFile.set(f.path, collectSuppressions(f.ast, f.path, totalLines));
+    rangesPerFile.set(f.path, collectSuppressions(f.ast, f.path, totalLines, f.content));
   }
   const ctx = { files: sourceFiles };
   let raw;
@@ -15610,6 +15825,20 @@ predicate satisfaction fraction, or edge-case messages for files inside
 Run this whenever you add or modify a type's \`when\` predicate and want
 to verify that existing files are classified as expected.
 
+## Glob patterns in mapping and when.path
+
+Both node \`mapping:\` entries and architecture \`when.path\` predicates accept
+minimatch glob patterns. \`*\` matches any characters within a single path
+segment (does not cross \`/\`); \`**\` matches across path segments.
+
+Examples:
+- \`src/db/*Repository.cs\` \u2014 owns only files matching \`*Repository.cs\` directly
+  inside \`src/db/\`, not subdirectory files or non-matching files like \`Helper.cs\`.
+- \`src/**/*.ts\` \u2014 owns all \`.ts\` files anywhere under \`src/\` at any depth.
+
+Plain (non-glob) entries remain unchanged: an exact file path or a directory
+prefix (e.g. \`src/handlers\`) covers that file or all files beneath it.
+
 ## Aspect status in architecture default aspects
 
 Architecture-level default aspects (channel 3) may declare \`status:\` to
@@ -16013,7 +16242,11 @@ var content4 = `# Writing deterministic aspects
 A deterministic aspect declares \`reviewer: { type: deterministic }\` and ships
 a \`check.mjs\` file. The check runs locally at zero LLM cost and returns a
 \`Violation[]\`. Deterministic aspects do not use reviewer tiers \u2014
-\`reviewer.tier:\` is rejected together with \`type: deterministic\`.
+\`reviewer.tier:\` is rejected together with \`type: deterministic\`. Because the
+check reads files programmatically (no LLM prompt), the per-node character budget
+(\`quality.max_node_chars\` / \`oversized-node\`) does NOT apply to a node whose
+only effective aspects are deterministic \u2014 such a node may map an arbitrarily
+large area.
 
 There are two ways to scope a deterministic aspect:
 
@@ -16126,7 +16359,7 @@ arrives in the one \`check.mjs\` invocation.
 | \`walk(node, visitor)\` | \`(node, (n) => boolean|void) => void\` | DFS traversal; visitor returning \`false\` skips descent into that subtree |
 | \`report(file, node, message)\` | \`(file, TreeNode, string) => Violation\` | Build a \`{ file, line, column, message }\` \u2014 \`line\` 1-based, \`column\` 0-based |
 | \`inFile(file, pattern)\` | \`(file, { glob } | { regex } | { contains }) => boolean\` | Path filter (discriminated object form) |
-| \`findComments(target)\` | \`(file | node) => TreeNode[]\` | Returns comment nodes within the file or subtree |
+| \`findComments(target)\` | \`(file) => TreeNode[]\` | Returns comment nodes within a file (language derived from its path) |
 | \`closest(node, types)\` | \`(TreeNode, string[]) => TreeNode | null\` | Nearest ancestor whose \`type\` is in \`types\` |
 
 ## tree-sitter node API
@@ -16385,7 +16618,7 @@ parsed AST trees via \`ctx.parseAst\`:
 | \`closest(node, types)\` | \`(TreeNode, string[]) => TreeNode | null\` | Nearest ancestor of one of the given types |
 | \`report(file, node, message)\` | \`(file, TreeNode, string) => Violation\` | Build \`{ file, line, column, message }\` \u2014 line 1-based, column 0-based |
 | \`inFile(file, pattern)\` | \`(file, { glob } | { regex } | { contains }) => boolean\` | Path filter |
-| \`findComments(target)\` | \`(file | node) => TreeNode[]\` | Returns comment nodes |
+| \`findComments(target)\` | \`(file) => TreeNode[]\` | Returns comment nodes |
 
 These helpers are optional \u2014 most graph-aware checks work purely with \`ctx.graph\`
 and \`ctx.fs\` without parsing AST trees at all.
@@ -16890,6 +17123,21 @@ For generated files where the entire file is exempt, place the marker at
 the file level (outside any function or class). At file level, the
 contextual scope is the whole file.
 
+## Language support
+
+Markers are recognized in any source language, using whichever comment syntax
+the language provides \u2014 \`//\` and \`/* */\` (C-family), \`#\` (shell, Python),
+\`--\` (SQL), and so on. The marker token \`yg-suppress(...)\` is what is matched,
+not a specific comment style.
+
+For a file whose extension has a registered grammar, markers are read from the
+file's comments, so a \`yg-suppress(...)\` that merely appears inside a string
+literal is NOT treated as a marker. For a file whose extension has no registered
+grammar (e.g. \`.sql\`, \`.md\`, \`.sh\`), there is no parse tree, so markers are
+found by scanning the raw lines \u2014 which is what lets a content-only deterministic
+check waive a violation in such a file. (In that raw-scan mode a marker token
+sitting inside a string literal would also match, so keep markers in comments.)
+
 ## Reason text
 
 The reason text after the aspect-id is permanent. Future maintainers and
@@ -17156,7 +17404,7 @@ reviewer:
       config:
         model: qwen3              # Model identifier for this provider
         temperature: 0            # Sampling temperature (0 = deterministic)
-        endpoint: http://localhost:11434   # Required for ollama and openai-compatible
+        endpoint: http://localhost:11434   # Required for openai-compatible (no default host); ollama defaults to localhost:11434
       # references:                         # optional caps on aspect reference files
       #   max_bytes_per_file: 65536         # default: 64 KiB per reference file
       #   max_total_bytes_per_aspect: 262144  # default: 256 KiB total per aspect
@@ -17168,7 +17416,7 @@ coverage:                           # Optional \u2014 controls which files must
 
 quality:
   max_direct_relations: 10        # Max out-edges per node before high-fan-out warning
-  max_node_chars: 40000           # Per-node character budget (source + aspect refs) before oversized-node error
+  max_node_chars: 40000           # Per-node char budget (source + aspect refs); oversized-node error \u2014 LLM-reviewed nodes only
 
 parallel: 1                       # Concurrent aspect verifications across nodes (default: 1)
 
@@ -17235,7 +17483,7 @@ Provider-specific options passed to the LLM client:
 |---|---|---|
 | \`model\` | string | Required. Provider-specific model identifier. |
 | \`temperature\` | number | Defaults to 0. Higher = more varied responses. |
-| \`endpoint\` | string | Required for \`ollama\` and \`openai-compatible\`. |
+| \`endpoint\` | string | Required for \`openai-compatible\` (no default host \u2014 else falls back to api.openai.com); \`ollama\` defaults to http://localhost:11434. |
 | \`timeout\` | number | Timeout in seconds. Default 300. Applies to CLI providers only \u2014 non-CLI/API providers ignore it. |
 
 API keys do NOT live here \u2014 they belong in \`yg-secrets.yaml\` (api_key only).
@@ -17306,18 +17554,20 @@ repository \u2014 it is safe to share.
 \`\`\`yaml
 coverage:
   required:
-    - src/       # unmapped files under src/ are a blocking error
+    - src/                  # unmapped files under src/ are a blocking error
   excluded:
-    - vendor/    # silently ignored
+    - vendor/               # silently ignored
+    - "**/*.generated.ts"   # glob: drop generated files anywhere
 \`\`\`
 
 Controls which git-tracked files must be mapped to a node.
 
-- \`required\` \u2014 path roots where unmapped files are a blocking \`unmapped-files\` error. Default: \`["/"]\` (whole repo \u2014 the previous always-map-everything behavior).
-- \`excluded\` \u2014 path roots that are silently ignored. Default: \`[]\`.
+- \`required\` \u2014 roots where unmapped files are a blocking \`unmapped-files\` error. Default: \`["/"]\` (whole repo \u2014 the previous always-map-everything behavior). An explicit empty list \`[]\` means require nothing: every uncovered file (outside \`excluded\`/nested) becomes a non-blocking \`uncovered-advisory\` warning and nothing blocks (pure-advisory adoption). Empty only counts when written explicitly; omitting the \`coverage\` block keeps the \`["/"]\` default.
+- \`excluded\` \u2014 roots that are silently ignored. Default: \`[]\`.
+- Roots accept the same forms as a node \`mapping:\` entry: an exact file, a directory prefix (e.g. \`src/\` covers everything beneath it), or a glob (\`*\` within a segment, \`**\` across) \u2014 so \`excluded: ["**/*.generated.ts"]\` drops generated files anywhere and \`required: ["services/*/api/**"]\` scopes the blocking tier to a pattern. \`/\` still means the whole repo.
 - Files that match neither a required nor an excluded root produce a non-blocking \`uncovered-advisory\` warning.
 - Subtrees containing their own nested \`.yggdrasil/\` are auto-skipped by all repo-walking checks (they are governed by their own graph).
-- Longest-match wins; on a tie between required and excluded, excluded wins.
+- Longest-match wins (by normalized root/pattern length); on a tie between required and excluded, excluded wins.
 
 ## Quality thresholds
 
@@ -17330,6 +17580,9 @@ quality:
 \`max_direct_relations\` fires a warning when exceeded. \`max_node_chars\` is a
 blocking error: a node whose mapped source plus aspect reference files exceed it
 (binary files do not count) must be split into children to stay under the budget.
+The budget applies only to nodes an LLM reviewer actually reads \u2014 those with at
+least one non-draft LLM aspect; deterministic-only and aspect-less nodes are not
+bounded (a check.mjs reads files programmatically, with no context window).
 For a node mapping a single unsplittable generated or binary artifact (a lockfile,
 an append-only changelog, an image), opt out per-node with
 \`sizeExempt: { reason: "<why it cannot be split>" }\`.
@@ -17396,8 +17649,9 @@ Unified gate \u2014 runs all validators in sequence.
 yg check
 \`\`\`
 
-Detects: drift (source + cascade), validation errors, coverage gaps,
-\`unmapped-files\`, type-when mismatches, strict orphans/misplaced files.
+Detects: drift (source + cascade), validation errors, coverage gaps
+(\`unmapped-files\` errors under required roots, \`uncovered-advisory\` warnings
+outside them), type-when mismatches, strict orphans/misplaced files.
 
 Exit 0 = clean. Exit 1 = errors found. CI blocks on exit 1.
 
@@ -17808,8 +18062,10 @@ ports:                                  # map keyed by port name (NOT a list)
 \`\`\`
 
 Every aspect id listed in a port's \`aspects\` must be defined under
-\`aspects/\`; a missing one emits a blocking error (code
-\`port-missing-aspect\`).
+\`aspects/\`. An undefined id is caught unconditionally by the
+reference-integrity check (code \`aspect-undefined\`); when the port is
+actually consumed, the missing aspect additionally surfaces as
+\`port-missing-aspect\`.
 
 A consumer references the port via the relation's \`consumes\`. In
 \`yg-node.yaml\`, \`relations:\` is a flat list and each entry carries its own
@@ -17854,12 +18110,11 @@ a blocking error on the missing port contract, surfacing the gap.
 
 If a target node declares ports and the consumer's relation does NOT
 declare \`consumes\`, \`yg check\` emits a blocking error (code
-\`port-missing-consumes\`) that fails the architecture gate:
-
-\`\`\`
-Missing port contract: <consumer> \u2192 <target> has ports [<list>],
-consumer must declare consumes: [<port-name>].
-\`\`\`
+\`port-missing-consumes\`) that fails the architecture gate. Like every
+diagnostic, it is rendered in the what/why/next form: it names the
+relation, explains that the target's port-required aspects won't be
+verified without a \`consumes\` declaration, and tells you to add
+\`consumes: [<port-names>]\` to the relation.
 
 There is no "accept the gap" mechanism. Resolve it one of two ways:
 declare which port(s) you consume on the relation, or remove the ports