@skill-graph/cli 0.5.6

package/scripts/lib/mock-grader.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * mock-grader.js — deterministic stand-in for an external grader CLI.
+ *
+ * Use this to smoke-test `scripts/skill-audit.js --graded` without an API
+ * key. It reads the composed prompt from stdin, pattern-matches the
+ * dimension id, and prints a canned <verdict>…</verdict> block on stdout
+ * that the audit runner can parse and merge into the artifact files.
+ *
+ * Usage (from the repo root):
+ *   node scripts/skill-audit.js documentation \
+ *        --graded \
+ *        --grader-cli "node scripts/lib/mock-grader.js" \
+ *        --force
+ *
+ * Self-contained — only Node built-ins. Exit 0 on success, 1 on error.
+ */
+
+'use strict';
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end',  () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function extractDimensionId(prompt) {
+  const m = prompt.match(/<dimension id="([a-z]+)"/);
+  return m ? m[1] : 'unknown';
+}
+
+// Canned per-dimension verdicts. Intentionally varied so the merged artifacts
+// show all four verdict states (PASS, PASS WITH FIXES, FAIL, N/A) and all five
+// severity levels. These are NOT real audit judgments — they exist to prove
+// the contract end-to-end.
+const CANNED = {
+  metadata: {
+    score: 5,
+    verdict: 'PASS',
+    justification: 'All thirteen required v2 frontmatter fields are present and well-typed; schema_version is 2.',
+    findings: [],
+  },
+  activation: {
+    score: 4,
+    verdict: 'PASS WITH FIXES',
+    justification: 'Description names real trigger scenarios and keywords are specific, but the skill has no explicit `triggers` array for label-based routing.',
+    findings: [
+      {
+        severity: 'P3',
+        surface: 'frontmatter: triggers',
+        problem: 'No triggers array is declared; the skill is only discoverable via keyword matching.',
+        evidence: 'triggers: (absent from frontmatter)',
+        required_action: 'Add a `triggers: [documentation-skill]` entry so label-based routers can activate the skill deterministically.',
+      },
+    ],
+  },
+  relation: {
+    score: 5,
+    verdict: 'PASS',
+    justification: 'adjacent and boundary relations are concise and point at real sibling skills; no dangling targets.',
+    findings: [],
+  },
+  grounding: {
+    score: 'N/A',
+    verdict: 'N/A',
+    justification: 'scope: portable — grounding dimension does not apply.',
+    findings: [],
+  },
+  content: {
+    score: 4,
+    verdict: 'PASS WITH FIXES',
+    justification: 'Coverage, Philosophy, and Verification sections are present and concrete, but "Do NOT Use When" boundaries are implicit rather than an explicit named section.',
+    findings: [
+      {
+        severity: 'P2',
+        surface: 'skill body',
+        problem: 'No explicit `## Do NOT Use When` section; negative routing is only implied.',
+        evidence: 'Section headings observed: `# Documentation`, `## Coverage`, `## Philosophy`, `## Verification` — no explicit negative-bounds section.',
+        required_action: 'Add a `## Do NOT Use When` section listing at least two cases where the skill must not activate (e.g. UI accessibility behavior, runtime debugging).',
+      },
+    ],
+  },
+  eval: {
+    score: 4,
+    verdict: 'PASS WITH FIXES',
+    justification: 'Eval artifact ships with seven grounded prompts; boundary coverage is good, but failure-mode prompts are missing.',
+    findings: [
+      {
+        severity: 'P3',
+        surface: 'examples/evals/comprehension.json',
+        problem: 'Eval covers happy-path and boundary prompts but has no explicit failure-mode eval.',
+        evidence: 'Seven prompts, all affirmative; no prompt tests what the skill should refuse.',
+        required_action: 'Add one failure-mode prompt per skills/evaluation SKILL.md guidance (≥ 1 negative expectation per skill).',
+      },
+    ],
+  },
+  portability: {
+    score: 5,
+    verdict: 'PASS',
+    justification: 'Skill is generic, portable, and the skill-md export via scripts/export-skill.js round-trips cleanly.',
+    findings: [],
+  },
+};
+
+(async function main() {
+  try {
+    const prompt = await readStdin();
+    const dimId  = extractDimensionId(prompt);
+    const payload = CANNED[dimId] || {
+      score: 'N/A',
+      verdict: 'N/A',
+      justification: `mock-grader has no canned verdict for dimension "${dimId}".`,
+      findings: [],
+    };
+
+    const body = {
+      dimension: dimId,
+      score: payload.score,
+      verdict: payload.verdict,
+      justification: payload.justification,
+      findings: payload.findings,
+    };
+
+    process.stdout.write('<verdict>\n' + JSON.stringify(body, null, 2) + '\n</verdict>\n');
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`mock-grader error: ${err.message}\n`);
+    process.exit(1);
+  }
+})();

package/scripts/lib/parse-frontmatter.js

@@ -0,0 +1,429 @@
+#!/usr/bin/env node
+/**
+ * Minimal YAML frontmatter parser for the subset used in Skill Graph SKILL.md
+ * files. Handles: scalar keys, quoted strings, block sequences, nested objects,
+ * block sequences of objects (v3 boundary/depends_on `- skill: ... reason: ...`
+ * form), inline comments, and inline maps (`key: { a: 1, b: 2 }`) at leaf level.
+ *
+ * Extracted from scripts/skill-lint.js so skill-lint, generate-manifest,
+ * export-skill, skill-graph-route, and skill-graph-drift can share the same
+ * parser without duplication.
+ *
+ * Usage:
+ *   const { parseFrontmatter } = require('./lib/parse-frontmatter');
+ *   const fm = parseFrontmatter(markdownText);  // returns object or null
+ */
+
+'use strict';
+
+/**
+ * Parse the YAML frontmatter block from a Markdown string.
+ *
+ * @param {string} text - Full contents of the Markdown file.
+ * @returns {object|null} Parsed frontmatter as a plain object, or null if no
+ *   frontmatter block is found.
+ */
+function parseFrontmatter(text) {
+  const m = text.match(/^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+  if (!m) return null;
+  const lines = m[1].split(/\r?\n/);
+  let i = 0;
+
+  /**
+   * Strip a trailing YAML inline comment from a scalar value.
+   *
+   * Rules (YAML 1.2): an inline comment starts at a `#` preceded by
+   * whitespace and runs to end-of-line. A `#` inside a quoted string does
+   * NOT start a comment. This matters for `examples` / `anti_examples`
+   * arrays where authors annotate hard-negative prompts with `# reason`
+   * tails — the intent is documentation, not part of the routing signal.
+   *
+   * Handles three cases:
+   *   1. Value starts with a quote — find the matching close quote, then
+   *      everything after it up to an optional `  #` tail is stripped.
+   *   2. Unquoted value — the first ` #` sequence begins the comment.
+   *   3. Value contains no `#` — return unchanged.
+   */
+  function stripInlineComment(raw) {
+    if (raw.length === 0) return raw;
+    const first = raw[0];
+    if (first === '"' || first === "'") {
+      // Scan for the matching close quote.
+      for (let idx = 1; idx < raw.length; idx++) {
+        if (raw[idx] === '\\') { idx++; continue; }
+        if (raw[idx] === first) {
+          // Found close quote. Trim everything after it if it matches ` #...`.
+          const tail = raw.slice(idx + 1);
+          const commentMatch = tail.match(/^\s+#/);
+          if (commentMatch) return raw.slice(0, idx + 1);
+          return raw;
+        }
+      }
+      // Unterminated quote — leave the author's text alone.
+      return raw;
+    }
+    // Unquoted: find ` #` (space-hash).
+    const m = raw.match(/\s+#/);
+    if (m) return raw.slice(0, m.index);
+    return raw;
+  }
+
+  function splitTopLevel(value, separator) {
+    const parts = [];
+    let start = 0;
+    let depth = 0;
+    let quote = null;
+    for (let idx = 0; idx < value.length; idx++) {
+      const ch = value[idx];
+      if (quote) {
+        if (ch === '\\') { idx++; continue; }
+        if (ch === quote) quote = null;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        quote = ch;
+        continue;
+      }
+      if (ch === '[' || ch === '{') {
+        depth++;
+        continue;
+      }
+      if (ch === ']' || ch === '}') {
+        depth--;
+        continue;
+      }
+      if (ch === separator && depth === 0) {
+        parts.push(value.slice(start, idx).trim());
+        start = idx + 1;
+      }
+    }
+    parts.push(value.slice(start).trim());
+    return parts.filter(Boolean);
+  }
+
+  function findTopLevelColon(value) {
+    let depth = 0;
+    let quote = null;
+    for (let idx = 0; idx < value.length; idx++) {
+      const ch = value[idx];
+      if (quote) {
+        if (ch === '\\') { idx++; continue; }
+        if (ch === quote) quote = null;
+        continue;
+      }
+      if (ch === '"' || ch === "'") {
+        quote = ch;
+        continue;
+      }
+      if (ch === '[' || ch === '{') {
+        depth++;
+        continue;
+      }
+      if (ch === ']' || ch === '}') {
+        depth--;
+        continue;
+      }
+      if (ch === ':' && depth === 0) return idx;
+    }
+    return -1;
+  }
+
+  function parseInlineArray(v) {
+    const body = v.slice(1, -1).trim();
+    if (body === '') return [];
+    return splitTopLevel(body, ',').map(parseValue);
+  }
+
+  function parseInlineMap(v) {
+    const body = v.slice(1, -1).trim();
+    if (body === '') return {};
+    const obj = {};
+    for (const part of splitTopLevel(body, ',')) {
+      const colonIdx = findTopLevelColon(part);
+      if (colonIdx <= 0) return v;
+      const key = extractKey(part.slice(0, colonIdx));
+      const rawValue = part.slice(colonIdx + 1).trim();
+      obj[key] = parseValue(rawValue);
+    }
+    return obj;
+  }
+
+  function parseValue(v) {
+    v = stripInlineComment(v).trim();
+    if (v === '') return null;
+    if (v.startsWith('[') && v.endsWith(']')) return parseInlineArray(v);
+    if (v.startsWith('{') && v.endsWith('}')) return parseInlineMap(v);
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+      return v.slice(1, -1);
+    }
+    if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+    if (/^-?\d+\.\d+$/.test(v)) return parseFloat(v);
+    if (v === 'true') return true;
+    if (v === 'false') return false;
+    if (v === 'null' || v === '~') return null;
+    return v;
+  }
+
+  /**
+   * Find the index of the key-separator colon in a YAML line. Handles quoted
+   * keys — a key like `"schemas/foo.json":` has a colon inside the quoted
+   * string that is NOT the separator. Returns the index of the separating
+   * colon or -1 when none is found.
+   */
+  function findKeyColon(content) {
+    if (content.startsWith('"') || content.startsWith("'")) {
+      const quote = content[0];
+      let i = 1;
+      while (i < content.length) {
+        if (content[i] === '\\') { i += 2; continue; }
+        if (content[i] === quote) break;
+        i++;
+      }
+      // i is at the closing quote; look for `:` after it
+      const afterQuote = content.indexOf(':', i + 1);
+      return afterQuote;
+    }
+    return content.indexOf(':');
+  }
+
+  /**
+   * Extract the key portion from a "key: value" line, unquoting if the key
+   * was wrapped in quotes.
+   */
+  function extractKey(raw) {
+    const trimmed = raw.trim();
+    if ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+        (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+      return trimmed.slice(1, -1);
+    }
+    return trimmed;
+  }
+
+  /**
+   * Parse a block sequence (array). Supports:
+   *   - scalar items:        "- string"
+   *   - inline objects:      "- { key: value }"
+   *   - block-mapping items: "- key: value\n  nextKey: value"
+   *
+   * The sequence ends when a line's indent drops to or below `indent`, or
+   * when the block is exhausted.
+   */
+  function parseBlockSequence(indent) {
+    const arr = [];
+    while (i < lines.length) {
+      const l = lines[i];
+      if (l.trim() === '' || l.trim().startsWith('#')) { i++; continue; }
+      const li = l.match(/^ */)[0].length;
+      if (li <= indent) break;
+      const lc = l.slice(li);
+      if (!lc.startsWith('- ')) break;
+
+      const inline = lc.slice(2).trim();
+
+      if ((inline.startsWith('{') && inline.endsWith('}')) ||
+          (inline.startsWith('[') && inline.endsWith(']'))) {
+        arr.push(parseValue(inline));
+        i++;
+        continue;
+      }
+
+      // Block mapping as an item: "- key: value" optionally followed by
+      // more keys at indent (li + 2). Distinguish from scalar items like
+      // "- http://example.com" (no space after colon) or `- "a:b"` (quoted).
+      const isQuoted = inline.startsWith('"') || inline.startsWith("'");
+      const colonIdx = isQuoted ? -1 : inline.indexOf(': ');
+      const endsWithColon = !isQuoted && inline.endsWith(':');
+
+      if (!isQuoted && (colonIdx > 0 || endsWithColon)) {
+        // Parse as object item.
+        const obj = {};
+        const itemIndent = li + 2;
+
+        // First key on the dash line.
+        if (endsWithColon) {
+          const k = inline.slice(0, -1).trim();
+          i++;
+          // The value of the first key is whatever follows at deeper indent.
+          // Leave it for the subsequent-key loop to handle — we just record
+          // the key as null so downstream code sees it as present.
+          obj[k] = null;
+        } else {
+          const k = inline.slice(0, colonIdx).trim();
+          const v = inline.slice(colonIdx + 1).trim();
+          obj[k] = parseValue(v);
+          i++;
+        }
+
+        // Subsequent keys at itemIndent belong to this object.
+        while (i < lines.length) {
+          const nl = lines[i];
+          if (nl.trim() === '' || nl.trim().startsWith('#')) { i++; continue; }
+          const nli = nl.match(/^ */)[0].length;
+          if (nli < itemIndent) break;
+          if (nli === itemIndent) {
+            const nlc = nl.slice(nli);
+            if (nlc.startsWith('- ')) break;  // next item in the outer sequence
+            const ci = nlc.indexOf(':');
+            if (ci <= 0) break;
+            const k = nlc.slice(0, ci).trim();
+            const v = nlc.slice(ci + 1).trim();
+            i++;
+            if (v === '') {
+              // Nested block — parse recursively at deeper indent.
+              let peek = i;
+              while (peek < lines.length && (lines[peek].trim() === '' || lines[peek].trim().startsWith('#'))) peek++;
+              if (peek < lines.length) {
+                const peekIndent = lines[peek].match(/^ */)[0].length;
+                const peekContent = lines[peek].slice(peekIndent);
+                if (peekIndent > itemIndent && peekContent.startsWith('- ')) {
+                  obj[k] = parseBlockSequence(itemIndent);
+                } else if (peekIndent > itemIndent) {
+                  obj[k] = parseBlock(peekIndent);
+                } else {
+                  obj[k] = null;
+                }
+              }
+            } else {
+              obj[k] = parseValue(v);
+            }
+          } else {
+            // Deeper indent without a matching itemIndent sibling — skip
+            // gracefully; authors using exotic indent should fall back to
+            // single-line scalars.
+            i++;
+          }
+        }
+
+        arr.push(obj);
+      } else {
+        arr.push(parseValue(inline));
+        i++;
+      }
+    }
+    return arr;
+  }
+
+  function parseBlock(indent) {
+    const result = {};
+    while (i < lines.length) {
+      const line = lines[i];
+      if (line.trim() === '' || line.trim().startsWith('#')) { i++; continue; }
+      const currentIndent = line.match(/^ */)[0].length;
+      if (currentIndent < indent) return result;
+      if (currentIndent > indent) { i++; continue; }
+      const content = line.slice(indent);
+      const colonIdx = findKeyColon(content);
+      if (colonIdx === -1) { i++; continue; }
+      const key = extractKey(content.slice(0, colonIdx));
+      const rest = content.slice(colonIdx + 1).trim();
+      i++;
+      if (rest === '') {
+        let peek = i;
+        while (peek < lines.length && (lines[peek].trim() === '' || lines[peek].trim().startsWith('#'))) peek++;
+        if (peek < lines.length) {
+          const peekLine = lines[peek];
+          const peekIndent = peekLine.match(/^ */)[0].length;
+          const peekContent = peekLine.slice(peekIndent);
+          if (peekIndent > indent && peekContent.startsWith('- ')) {
+            result[key] = parseBlockSequence(indent);
+          } else if (peekIndent > indent) {
+            result[key] = parseBlock(peekIndent);
+          } else {
+            result[key] = null;
+          }
+        }
+      } else {
+        result[key] = parseValue(rest);
+      }
+    }
+    return result;
+  }
+
+  return parseBlock(0);
+}
+
+// Set of base SKILL.md fields that stay at the top level in the marketplace
+// export shape. Anything else found under `metadata:` is a Skill Graph
+// extension field that the export pipeline relocated to satisfy Anthropic
+// Claude Code's frontmatter contract. The normalizer lifts those back to
+// top-level so downstream consumers (lint, manifest, route, drift) can read
+// the canonical shape regardless of which format the file is in.
+const SKILL_MD_BASE_FIELDS = new Set([
+  'name',
+  'description',
+  'license',
+  'compatibility',
+  'allowed-tools',
+]);
+
+// Provenance fields added by the export pipeline (see
+// scripts/export-marketplace-skills.js § PROVENANCE_KEYS and the related
+// description-length book-keeping fields). These are export-only metadata
+// describing where the marketplace file came from; they are not authoring
+// fields and the canonical schema does not declare them. The normalizer
+// strips them so lint and manifest tooling see only the authored shape.
+const EXPORT_PROVENANCE_FIELDS = new Set([
+  'skill_graph_source_repo',
+  'skill_graph_protocol',
+  'skill_graph_project',
+  'skill_graph_canonical_skill',
+  'skill_graph_export_description',
+  'skill_graph_canonical_description_length',
+]);
+
+/**
+ * Convert a parsed frontmatter object from the marketplace export shape
+ * (Skill Graph extension fields nested under `metadata:`, complex values
+ * JSON-stringified) back to the canonical Skill Graph shape (all fields at
+ * top-level, complex values as native arrays/objects).
+ *
+ * Idempotent: a canonical-shape input returns unchanged (modulo a defensive
+ * copy). Top-level fields take precedence over `metadata.*` if both are
+ * present — the explicit author signal wins.
+ *
+ * @param {object|null} fm - Parsed frontmatter (output of parseFrontmatter).
+ * @returns {object|null} Canonicalized frontmatter, or null/undefined passthrough.
+ */
+function normalizeFrontmatter(fm) {
+  if (!fm || typeof fm !== 'object') return fm;
+  const metadata = fm.metadata;
+  if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    return fm;
+  }
+
+  const normalized = { ...fm };
+  delete normalized.metadata;
+
+  for (const [key, rawValue] of Object.entries(metadata)) {
+    if (EXPORT_PROVENANCE_FIELDS.has(key)) continue;
+    // Top-level wins. Authors who explicitly set both forms get the
+    // top-level version preserved without surprise.
+    if (key in normalized && !SKILL_MD_BASE_FIELDS.has(key)) continue;
+
+    // Marketplace export JSON-stringifies arrays and objects so the resulting
+    // YAML stays a flat string-to-string map. Restore native shape here.
+    //
+    // Two unescape passes are needed in order: our parseFrontmatter does not
+    // currently decode YAML double-quote escape sequences (`\"` → `"`,
+    // `\\` → `\`), so the raw value still contains literal backslashes from
+    // the on-disk representation. Strip those before JSON.parse.
+    if (typeof rawValue === 'string') {
+      const trimmed = rawValue.trim();
+      if ((trimmed.startsWith('[') && trimmed.endsWith(']')) ||
+          (trimmed.startsWith('{') && trimmed.endsWith('}'))) {
+        const yamlUnescaped = trimmed.replace(/\\"/g, '"').replace(/\\\\/g, '\\');
+        try {
+          normalized[key] = JSON.parse(yamlUnescaped);
+          continue;
+        } catch (_err) {
+          // Not valid JSON — fall through and keep the raw string.
+        }
+      }
+    }
+    normalized[key] = rawValue;
+  }
+
+  return normalized;
+}
+
+module.exports = { parseFrontmatter, normalizeFrontmatter };

package/scripts/lib/roots.js

@@ -0,0 +1,119 @@
+/**
+ * Root resolution for local development and installed CLI usage.
+ *
+ * The npm package lives in its own package root, but most commands should act
+ * on the caller's workspace. `bin/skill-graph.js` sets SKILL_GRAPH_WORKSPACE
+ * to the process cwd before spawning a script; direct `node scripts/*.js`
+ * calls fall back to the current working directory.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PACKAGE_ROOT = process.env.SKILL_GRAPH_PACKAGE_ROOT
+  ? path.resolve(process.env.SKILL_GRAPH_PACKAGE_ROOT)
+  : path.resolve(__dirname, '..', '..');
+
+function workspaceRoot() {
+  return path.resolve(process.env.SKILL_GRAPH_WORKSPACE || process.env.SKILL_GRAPH_ROOT || process.cwd());
+}
+
+function packageRoot() {
+  return PACKAGE_ROOT;
+}
+
+function resolvePackagedOrWorkspacePath(root, ...parts) {
+  const workspacePath = path.join(root, ...parts);
+  if (fs.existsSync(workspacePath)) return workspacePath;
+  return path.join(PACKAGE_ROOT, ...parts);
+}
+
+function resolveSchemaPath(root, fileName) {
+  return resolvePackagedOrWorkspacePath(root, 'schemas', fileName);
+}
+
+function loadWorkspaceConfig(root = workspaceRoot(), onWarning = null) {
+  const configPath = path.join(root, '.skill-graph', 'config.json');
+  if (!fs.existsSync(configPath)) return null;
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (!config || typeof config !== 'object') return null;
+    if (!config.workspace || typeof config.workspace !== 'object') return null;
+    return config.workspace;
+  } catch (e) {
+    if (typeof onWarning === 'function') {
+      onWarning(`.skill-graph/config.json: cannot parse - ${e.message}`);
+    }
+    return null;
+  }
+}
+
+function resolveSkillRoots(root = workspaceRoot(), workspace = loadWorkspaceConfig(root)) {
+  const defaultRoot = { absPath: path.join(root, 'skills'), project: null };
+  if (!workspace || !Array.isArray(workspace.skill_roots) || workspace.skill_roots.length === 0) {
+    return [defaultRoot];
+  }
+
+  return workspace.skill_roots
+    .map(entry => {
+      if (typeof entry === 'string') {
+        return { absPath: path.resolve(root, entry), project: null };
+      }
+      if (entry && typeof entry === 'object' && typeof entry.path === 'string') {
+        return {
+          absPath: path.resolve(root, entry.path),
+          project: (typeof entry.project === 'string' && entry.project.length > 0) ? entry.project : null,
+        };
+      }
+      return null;
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Resolve a truth_source-style workspace-relative path against the configured
+ * skill library, falling back to the repo root for back-compat.
+ *
+ * Truth_source paths in eval files and `grounding.truth_sources` blocks look
+ * like `skills/<name>/SKILL.md` — workspace-relative to where the skill
+ * library lives. Pre-2026-05-16 monorepo split, that was always
+ * `<repo-root>/skills/<name>/SKILL.md`. Post-split, the skill library can
+ * live in a sibling repo configured via `.skill-graph/config.json` →
+ * `workspace.skill_roots`. This helper tries the skill-library-aware
+ * resolution first when the relPath starts with `skills/` and the configured
+ * skill_root's basename is `skills`, then falls back to repo-root resolution.
+ *
+ * Behavior:
+ *   - Default workspace (no config, skill_roots = ["./skills"]):
+ *     `skills/a11y/SKILL.md` → `<repo-root>/skills/a11y/SKILL.md` (unchanged)
+ *   - Configured workspace (skill_roots = ["../skills/skills"]):
+ *     `skills/a11y/SKILL.md` → `<repo-root>/../skills/skills/a11y/SKILL.md`
+ *   - Paths that don't start with `skills/` (e.g., `schemas/foo.json`) always
+ *     resolve against `<repo-root>` — they reference the tooling repo itself.
+ *
+ * @param {string} relPath — workspace-relative path from a truth_source
+ * @param {string} repoRoot — the tooling repo workspace root (= REPO_ROOT)
+ * @param {Array<{absPath: string, project?: string|null}>} skillRoots — output of resolveSkillRoots()
+ * @returns {string} absolute path (existence not guaranteed)
+ */
+function resolveTruthSourcePath(relPath, repoRoot, skillRoots) {
+  if (typeof relPath === 'string' && relPath.startsWith('skills/') && Array.isArray(skillRoots) && skillRoots.length > 0) {
+    const firstRoot = skillRoots[0] && skillRoots[0].absPath;
+    if (firstRoot && path.basename(firstRoot) === 'skills') {
+      return path.resolve(path.dirname(firstRoot), relPath);
+    }
+  }
+  return path.resolve(repoRoot, relPath);
+}
+
+module.exports = {
+  packageRoot,
+  workspaceRoot,
+  loadWorkspaceConfig,
+  resolvePackagedOrWorkspacePath,
+  resolveSchemaPath,
+  resolveSkillRoots,
+  resolveTruthSourcePath,
+};