@hone-ai/cli 1.4.0

package/lib/skill-audit-render.js

@@ -0,0 +1,158 @@
+'use strict';
+/**
+ * skill-audit-render.js — SA-002 / #137 (architect plan story 2/2):
+ * pure renderer for the Step 5b skill-audit artifact.
+ *
+ * Takes the output of `runAssertions()` (cli/lib/skill-assertions.js) and
+ * produces a markdown artifact that satisfies the 3 structural markers
+ * from the synthetic-pipeline `story-that-violates-skill` fixture:
+ *
+ *   1. `^## Skill audit` heading (canonical artifact section, anchored)
+ *   2. skillId + assertionId co-occurrence on a single line
+ *   3. severity (BLOCKER|WARN|INFO) co-occurring with matchedFile path
+ *
+ * Pure helper, Category C (Transformation) per cli/lib/README.md taxonomy:
+ * takes structured input → returns transformed string output. No I/O.
+ *
+ * Architect's spec:
+ *   - Empty findings produce a VALID artifact (not a missing file)
+ *   - Severity carried through unchanged from the engine
+ *   - Exit-code-0 contract is enforced by the CLI shell, not the renderer
+ *
+ * Issue: #137 (story 2/2).
+ */
+
+/**
+ * Render a Step 5b skill-audit artifact from runAssertions() output.
+ *
+ * @param {object} opts
+ * @param {object} opts.result - return value of runAssertions(); must carry
+ *   `findings`, `scannedSkills`, `skipped`, `warnings`
+ * @param {string} opts.storyId - e.g. "SA-002"
+ * @param {string} opts.branchName - e.g. "feat/SA-002-step-5b-runner"
+ * @param {string} opts.baseBranch - e.g. "develop"
+ * @param {string[]} [opts.referencedSkills] - story's referenced_skill list
+ *   (LC-001 cross-ref); empty/undefined → "(all skills evaluated)"
+ * @param {string} [opts.generatedAt] - ISO timestamp; defaults to now
+ * @returns {string} markdown artifact text
+ */
+function renderStep5bArtifact(opts = {}) {
+  const result = opts.result || {};
+  const findings = Array.isArray(result.findings) ? result.findings : [];
+  const scannedSkills = Array.isArray(result.scannedSkills) ? result.scannedSkills : [];
+  const skipped = Array.isArray(result.skipped) ? result.skipped : [];
+  const warnings = Array.isArray(result.warnings) ? result.warnings : [];
+
+  const storyId = opts.storyId || '<unknown-story>';
+  const branchName = opts.branchName || '<unknown-branch>';
+  const baseBranch = opts.baseBranch || 'develop';
+  const generatedAt = opts.generatedAt || new Date().toISOString();
+  const referenced = Array.isArray(opts.referencedSkills) ? opts.referencedSkills : [];
+
+  const lines = [];
+  lines.push(`# ${storyId} — Step 5b: Skill Audit`);
+  lines.push('');
+  lines.push(`> Branch: \`${branchName}\` vs \`${baseBranch}\``);
+  lines.push(`> Generated: ${generatedAt}`);
+  lines.push(`> Engine: \`cli/lib/skill-assertions.js\` (SA-001 v1)`);
+  lines.push(`> Gating: **informational only** — exit-code-0 by contract; severity-to-gate mapping deferred to OptionsFlow E29-G.`);
+  lines.push('');
+
+  // ─── Marker 1: ^## Skill audit (canonical heading) ───
+  lines.push('## Skill audit');
+  lines.push('');
+
+  // Counts header — concise summary
+  const counts = countBySeverity(findings);
+  lines.push(`- skills scanned: **${scannedSkills.length}**${scannedSkills.length > 0 ? ' — ' + scannedSkills.map(s => '`' + s + '`').join(', ') : ''}`);
+  lines.push(`- skills skipped: **${skipped.length}**`);
+  lines.push(`- findings: **${findings.length}** (${counts.BLOCKER} BLOCKER · ${counts.WARN} WARN · ${counts.INFO} INFO)`);
+  lines.push(`- parse warnings: **${warnings.length}**`);
+  if (referenced.length > 0) {
+    lines.push(`- referenced_skill scope: ${referenced.map(s => '`' + s + '`').join(', ')}`);
+  } else {
+    lines.push(`- referenced_skill scope: _(none — all skills evaluated)_`);
+  }
+  lines.push('');
+
+  // ─── Findings table (Markers 2 + 3 satisfied per row) ───
+  if (findings.length === 0) {
+    lines.push('**0 assertions matched the diff.** Either no skill defined `## Assertions`, or no added line in this PR triggered any assertion.');
+    lines.push('');
+  } else {
+    lines.push('### Findings');
+    lines.push('');
+    lines.push('| skill | assertion | severity | file:line | description |');
+    lines.push('|---|---|---|---|---|');
+    for (const f of findings) {
+      const skillId = f.skillId || '?';
+      const assertionId = f.assertionId || '?';
+      const severity = f.severity || 'INFO';
+      const file = f.matchedFile || '?';
+      const line = f.matchedLine != null ? String(f.matchedLine) : '?';
+      const desc = (f.description || '').replace(/\|/g, '\\|');
+      // Marker 2: skill + assertion on same line ✓
+      // Marker 3: severity + file path on same line ✓
+      lines.push(`| \`${skillId}\` | \`${assertionId}\` | **${severity}** | \`${file}\`:${line} | ${desc} |`);
+    }
+    lines.push('');
+
+    // Per-finding details with the matched text (bounded for artifact size)
+    lines.push('### Matched text');
+    lines.push('');
+    for (const f of findings) {
+      const matched = (f.matchedText || '').replace(/`/g, '\\`');
+      lines.push(`- \`${f.skillId}\` / \`${f.assertionId}\` at \`${f.matchedFile}\`:${f.matchedLine}`);
+      lines.push(`  - pattern: \`${f.forbidAddedSrc || '?'}\``);
+      lines.push(`  - matched: \`${matched.slice(0, 200)}\``);
+    }
+    lines.push('');
+  }
+
+  // ─── Skipped skills (informational) ───
+  if (skipped.length > 0) {
+    lines.push('### Skipped');
+    lines.push('');
+    for (const s of skipped) {
+      lines.push(`- \`${s.skillId}\` — ${s.reason}`);
+    }
+    lines.push('');
+  }
+
+  // ─── Parse warnings (skill-author errors, surfaced for fixing) ───
+  if (warnings.length > 0) {
+    lines.push('### Parse warnings');
+    lines.push('');
+    lines.push('Skill authors: these are likely errors in your `## Assertions` block.');
+    lines.push('');
+    for (const w of warnings) {
+      lines.push(`- \`${w.skillId || '?'}\` — **${w.kind}**: ${w.message}`);
+    }
+    lines.push('');
+  }
+
+  // Footer: contract reference
+  lines.push('---');
+  lines.push('');
+  lines.push('Generated by `hone step-5b`. See [#137](https://github.com/subbareddyvani/hone-server/issues/137) for the runtime audit contract; SA-001 / SA-002 for the engine + runner.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Count findings by severity. Returns { BLOCKER, WARN, INFO }.
+ */
+function countBySeverity(findings) {
+  const out = { BLOCKER: 0, WARN: 0, INFO: 0 };
+  for (const f of findings) {
+    const s = f && f.severity;
+    if (s === 'BLOCKER' || s === 'WARN' || s === 'INFO') out[s] += 1;
+  }
+  return out;
+}
+
+module.exports = {
+  renderStep5bArtifact,
+  countBySeverity,
+};

package/lib/skill-audit.js

@@ -0,0 +1,391 @@
+'use strict';
+/**
+ * skill-audit.js — H-085 pure-helper-with-injected-I/O for skill auditing.
+ *
+ * Audits skills against the current codebase + learnings. Reports drift in
+ * three categories:
+ *   - PATH_BROKEN: skill mentions a file path that doesn't exist
+ *   - CROSS_REF_BROKEN: skill references "see skill X" where X doesn't exist
+ *   - SKILL_CANDIDATE: learnings tag `candidate_for: enterprise/skills/X`
+ *     where X doesn't exist (new skill overdue)
+ *
+ * LC-002 (#58 G2 partial, story 2/3): SKILL_CANDIDATE threshold is
+ * WEIGHTED by `category`. Only `discovered-new-pattern` learnings count
+ * toward the ≥2 threshold; `applied-existing-rule` and
+ * `exception-with-rationale` are excluded (they are compliance evidence
+ * and documented deviations, NOT promotion candidates). Missing category
+ * defaults to counted (back-compat for pre-LC-001 learnings).
+ *
+ * M scope. L scope deferred:
+ *   - Symbol-validity check (requires AST tooling)
+ *   - Origin-story freshness (requires git log scan)
+ *
+ * Issue: #85 (H-085) + #58 (LC-002).
+ */
+const yaml = require('js-yaml');
+const { LEARNING_CATEGORIES } = require('./learnings-parse');
+
+// AU-001 (#159): path-candidate verdicts. Each candidate string
+// extracted from skill markdown gets one of these verdicts; only
+// is_file_path triggers an existence check.
+const VERDICTS = Object.freeze({
+  IS_FILE_PATH:     'is_file_path',
+  IS_URL:           'is_url',
+  IS_PYTHON_DOTTED: 'is_python_dotted',
+  IS_CODE_BLOCK:    'is_code_block',
+  IS_INLINE_PROSE:  'is_inline_prose',
+  UNCLASSIFIED:     'unclassified',
+});
+
+// Known file-tree prefixes — paths starting with one of these are
+// strong-positive for is_file_path. Adopters with custom prefixes
+// can extend via .hone/audit-skills.ignore.yml (allow-list).
+const KNOWN_PATH_PREFIXES = [
+  'src/', 'lib/', 'tests/', 'docs/', 'scripts/',
+  '.github/', '.hone/', 'server/', 'cli/',
+  'pages/', 'app/', 'public/', 'assets/',
+  'config/', 'enterprise/', 'enterprise-assets/',
+];
+
+// Common file extensions — paths ending in one of these are
+// strong-positive for is_file_path.
+const KNOWN_FILE_EXTENSIONS = new Set([
+  'js', 'ts', 'jsx', 'tsx', 'mjs', 'cjs',
+  'py', 'rb', 'go', 'rs', 'java', 'kt',
+  'md', 'mdx', 'rst', 'txt',
+  'yml', 'yaml', 'json', 'toml', 'ini', 'env',
+  'sh', 'bash', 'zsh', 'fish',
+  'css', 'scss', 'sass', 'less',
+  'html', 'xml', 'svg',
+  'sql', 'dockerfile', 'makefile',
+]);
+
+/**
+ * AU-001: classify a candidate path string extracted from skill markdown.
+ *
+ * Verdicts (first match wins):
+ *   1. is_code_block      — ctx.inCodeBlock === true (skip path-checking)
+ *   2. is_url             — http(s)://, ://-scheme, system paths,
+ *                           or HTTP-shaped (module.X/Y like requests.get/post)
+ *   3. is_python_dotted   — has dotted name (foo.bar) — Python module ref
+ *   4. is_inline_prose    — contains " / " (space + slash) → prose
+ *   5. is_file_path       — known prefix OR known extension
+ *   6. unclassified       — none of the above; not flagged but no positive
+ *                           evidence. Caller can treat as low-signal.
+ *
+ * @param {string} p - the candidate path
+ * @param {object} ctx - { inCodeBlock?: boolean }
+ * @returns {{ verdict: string, reason: string }}
+ */
+function classifyPathCandidate(p, ctx = {}) {
+  if (typeof p !== 'string' || !p) {
+    return { verdict: VERDICTS.UNCLASSIFIED, reason: 'empty input' };
+  }
+
+  // 1. In-code-block check (architect AC-4): never path-check fenced content
+  if (ctx.inCodeBlock === true) {
+    return { verdict: VERDICTS.IS_CODE_BLOCK, reason: 'inside fenced code block' };
+  }
+
+  // 2a. URL / scheme / system path checks (existing behavior, retained)
+  if (p.startsWith('http://') || p.startsWith('https://') || p.includes('://')) {
+    return { verdict: VERDICTS.IS_URL, reason: 'starts with URL scheme' };
+  }
+  if (/^(usr|etc|tmp|var|opt)\//.test(p)) {
+    return { verdict: VERDICTS.IS_URL, reason: 'system path (treated as non-repo)' };
+  }
+  // Placeholders
+  if (/<[A-Z_a-z]\w*>|\$\{|\.\.\./.test(p)) {
+    return { verdict: VERDICTS.UNCLASSIFIED, reason: 'placeholder' };
+  }
+  if (/^path\/to\/|^example\/|^foo\/bar/.test(p)) {
+    return { verdict: VERDICTS.UNCLASSIFIED, reason: 'documentation placeholder' };
+  }
+
+  // 2b. HTTP-shape check (NEW): module.X/Y style → API endpoint
+  // Examples:
+  //   tradier./markets/quotes  ← starts with module-name then dot then /
+  //   requests.get/post        ← module.method / method
+  //   api.v1/users             ← module.subpath / resource
+  if (/^[a-z][a-z0-9_]*\.(?:[a-zA-Z_][a-zA-Z0-9_]*)?\/[a-zA-Z]/.test(p)) {
+    return { verdict: VERDICTS.IS_URL, reason: 'HTTP-shape (module.X/Y looks like API endpoint)' };
+  }
+
+  // 3. Python-dotted-name check (NEW): symbol references
+  // Examples:
+  //   src/indicators.detect_trap         (path/module.symbol)
+  //   src/session_phase.NO_TRADE_PHASES  (path/module.CONST)
+  // Pattern: trailing `.<identifier>` after a slash-segment, where the
+  // identifier is NOT a recognized file extension.
+  const trailingDotMatch = p.match(/^(.+\/)?([a-z_][a-zA-Z0-9_]*)\.([a-zA-Z_][a-zA-Z0-9_]*)$/);
+  if (trailingDotMatch) {
+    const ext = trailingDotMatch[3].toLowerCase();
+    if (!KNOWN_FILE_EXTENSIONS.has(ext)) {
+      // Not a known file extension → this is a dotted symbol reference,
+      // not a file path with extension.
+      return { verdict: VERDICTS.IS_PYTHON_DOTTED, reason: `trailing .${trailingDotMatch[3]} is not a known file extension` };
+    }
+  }
+
+  // 4. Forward-slash-with-space check (NEW): prose
+  if (/\s\/\s|\/\s|\s\//.test(p)) {
+    return { verdict: VERDICTS.IS_INLINE_PROSE, reason: 'contains space-adjacent slash (prose)' };
+  }
+
+  // 5a. Known prefix → is_file_path
+  for (const prefix of KNOWN_PATH_PREFIXES) {
+    if (p.startsWith(prefix)) {
+      return { verdict: VERDICTS.IS_FILE_PATH, reason: `starts with known prefix "${prefix}"` };
+    }
+  }
+
+  // 5b. Known extension → is_file_path
+  const extMatch = p.match(/\.([a-zA-Z0-9]+)$/);
+  if (extMatch && KNOWN_FILE_EXTENSIONS.has(extMatch[1].toLowerCase())) {
+    return { verdict: VERDICTS.IS_FILE_PATH, reason: `ends with known extension .${extMatch[1]}` };
+  }
+
+  // 6. Default
+  return { verdict: VERDICTS.UNCLASSIFIED, reason: 'no positive evidence; not flagged' };
+}
+
+/**
+ * AU-001: collect all path candidates from a skill's markdown content,
+ * tracking whether each candidate was inside a fenced code block.
+ *
+ * Returns: Array<{ path: string, inCodeBlock: boolean }>
+ */
+function collectPathCandidates(content) {
+  const candidates = [];
+  if (typeof content !== 'string' || !content) return candidates;
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+  // Inline-backtick path pattern (must contain a slash, must look path-shaped)
+  const inlineRe = /`([a-zA-Z][a-zA-Z0-9._\-/]*\/[a-zA-Z0-9._\-/]+(?:\.[a-zA-Z0-9]+)?)`/g;
+  // Bare-line path pattern (within code blocks; no backticks needed)
+  const bareLineRe = /\b([a-zA-Z][a-zA-Z0-9._\-/]*\/[a-zA-Z0-9._\-/]+\.[a-zA-Z0-9]+)\b/g;
+  for (const line of lines) {
+    // Track triple-backtick fences
+    if (/^\s*```/.test(line)) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) {
+      // Code-block lines: gather bare paths too (no backticks required;
+      // people write `src/foo.py` style without backticks inside fences)
+      let m;
+      while ((m = bareLineRe.exec(line)) !== null) {
+        candidates.push({ path: m[1], inCodeBlock: true });
+      }
+      bareLineRe.lastIndex = 0;
+    } else {
+      // Non-code-block lines: only inline-backtick-wrapped paths
+      let m;
+      while ((m = inlineRe.exec(line)) !== null) {
+        candidates.push({ path: m[1], inCodeBlock: false });
+      }
+      inlineRe.lastIndex = 0;
+    }
+  }
+  return candidates;
+}
+
+/** Simple glob matcher: `*` → any chars, `?` → one char. AU-001. */
+function globMatch(pattern, candidate) {
+  if (typeof pattern !== 'string' || typeof candidate !== 'string') return false;
+  const re = '^' + pattern
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')   // escape regex specials
+    .replace(/\*/g, '.*')
+    .replace(/\?/g, '.') + '$';
+  try { return new RegExp(re).test(candidate); }
+  catch { return false; }
+}
+
+/**
+ * Audit skills against codebase + learnings.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.skillFiles - SKILL.md content per skill (array of strings)
+ * @param {string[]} opts.skillNames - matching skill names
+ * @param {string[]} opts.learningsFiles - learnings YAML content per file
+ * @param {(relativePath: string) => boolean} opts.fileExists - filesystem check
+ * @returns {{ findings: Array<{severity, category, skill, message}>, summary: object }}
+ */
+function auditSkills(opts = {}) {
+  const { skillFiles = [], skillNames = [], learningsFiles = [], fileExists } = opts;
+  const findings = [];
+
+  if (typeof fileExists !== 'function') {
+    return { findings: [], summary: { error: 'missing fileExists callback' } };
+  }
+
+  const knownSkillSet = new Set(skillNames);
+
+  // AU-001 (#159): adopter-supplied allow-list. Entries match LITERALLY
+  // unless they contain * or ? (then treated as glob).
+  const ignoreList = Array.isArray(opts.ignoreList)
+    ? opts.ignoreList.filter(x => typeof x === 'string')
+    : [];
+  function isIgnored(p) {
+    for (const pattern of ignoreList) {
+      if (pattern === p) return true;
+      if ((pattern.includes('*') || pattern.includes('?')) && globMatch(pattern, p)) return true;
+    }
+    return false;
+  }
+
+  // ─── 1. Path validity per skill ───
+  for (let i = 0; i < skillFiles.length; i++) {
+    const content = skillFiles[i] || '';
+    const skillName = skillNames[i] || `<skill-${i}>`;
+    // AU-001 (#159): walk markdown line-by-line so we can track triple-backtick
+    // code-block state. Paths inside fenced code blocks are illustrative, not
+    // assertions about the repo layout.
+    const candidates = collectPathCandidates(content);
+    const seen = new Set();
+    for (const cand of candidates) {
+      const p = cand.path;
+      // De-dup
+      if (seen.has(p)) continue;
+      seen.add(p);
+
+      // AU-001 (#159): allow-list short-circuit
+      if (isIgnored(p)) continue;
+
+      // AU-001: classify the candidate. Verdicts other than is_file_path
+      // skip the existence check (URLs, code-block content, Python-dotted
+      // names, prose) without flagging.
+      const verdict = classifyPathCandidate(p, { inCodeBlock: cand.inCodeBlock }).verdict;
+      if (verdict !== 'is_file_path') continue;
+
+      // Skip cross-skill references (handled by category 2 — CROSS_REF_BROKEN)
+      // Pattern: `<some-skill>/SKILL.md` — don't double-flag.
+      if (/^[a-z-]+\/SKILL\.md$/.test(p)) continue;
+
+      if (!fileExists(p)) {
+        findings.push({
+          severity: 'ERROR',
+          category: 'PATH_BROKEN',
+          skill: skillName,
+          classifierVerdict: verdict,           // AU-001 AC-5: surface the call
+          message: `path "${p}" does not exist in repo`,
+        });
+      }
+    }
+  }
+
+  // ─── 2. Cross-skill-ref validity ───
+  for (let i = 0; i < skillFiles.length; i++) {
+    const content = skillFiles[i] || '';
+    const skillName = skillNames[i] || `<skill-${i}>`;
+    // Match "skill-name/SKILL.md" mentions in skill bodies
+    const refPattern = /`([a-z-]+)\/SKILL\.md`/g;
+    const seen = new Set();
+    let m;
+    while ((m = refPattern.exec(content)) !== null) {
+      const target = m[1];
+      if (target === skillName) continue; // self-reference is fine
+      if (seen.has(target)) continue;
+      seen.add(target);
+      if (!knownSkillSet.has(target)) {
+        findings.push({
+          severity: 'ERROR',
+          category: 'CROSS_REF_BROKEN',
+          skill: skillName,
+          message: `references "${target}/SKILL.md" but no such skill exists`,
+        });
+      }
+    }
+  }
+
+  // ─── 3. Untagged-pattern detection (new-skill candidates from learnings) ───
+  //
+  // LC-002: weight by `category` (LC-001 schema field). Only items that
+  // are categorized as `discovered-new-pattern` — OR have no category at
+  // all (back-compat for pre-LC-001 learnings) — count toward the ≥2
+  // threshold. `applied-existing-rule` and `exception-with-rationale`
+  // are excluded: they are compliance/deviation evidence, NOT signals
+  // that a new skill is overdue.
+  //
+  // Implementation: parse YAML once and walk items in any of the 3
+  // schemas; pick up `referenced_skill` (LC-001) || `candidate_for`
+  // (Schema B) || `skill_update` (Schema A) as the candidate skill.
+  const skillCandidates = new Map();  // name → { weighted, total, byCategory }
+  for (const lf of learningsFiles) {
+    if (!lf) continue;
+    let parsed;
+    try { parsed = yaml.load(lf); } catch { continue; }
+    if (!parsed) continue;
+
+    // Walk items in whichever schema this file uses.
+    const items = [];
+    if (Array.isArray(parsed)) {
+      items.push(...parsed);                                   // Schema A
+    } else if (typeof parsed === 'object') {
+      if (Array.isArray(parsed.enterprise_candidates)) items.push(...parsed.enterprise_candidates);  // Schema B
+      if (Array.isArray(parsed.learnings))             items.push(...parsed.learnings);              // Schema C
+    }
+
+    for (const item of items) {
+      if (!item || typeof item !== 'object') continue;
+      // Pick the candidate skill ref (in priority order).
+      const ref = item.referenced_skill || item.candidate_for || item.skill_update;
+      if (!ref || typeof ref !== 'string') continue;
+      // Strip enterprise/skills/ prefix and /SKILL.md suffix.
+      const candidate = ref.replace(/^enterprise\/skills\//, '').replace(/\/SKILL\.md$/, '');
+      if (!candidate || candidate.includes('/') || candidate.length < 3) continue;
+      if (knownSkillSet.has(candidate)) continue;
+
+      const cat = (typeof item.category === 'string' && item.category) || null;
+      // counts toward threshold: explicit discovered-new-pattern OR uncategorized
+      const counts = (cat === null || cat === LEARNING_CATEGORIES.DISCOVERED_NEW_PATTERN);
+
+      let entry = skillCandidates.get(candidate);
+      if (!entry) {
+        entry = { weighted: 0, total: 0, byCategory: { discovered: 0, applied: 0, exception: 0, uncategorized: 0 } };
+        skillCandidates.set(candidate, entry);
+      }
+      entry.total += 1;
+      if (counts) entry.weighted += 1;
+      if (cat === LEARNING_CATEGORIES.DISCOVERED_NEW_PATTERN) entry.byCategory.discovered += 1;
+      else if (cat === LEARNING_CATEGORIES.APPLIED_EXISTING_RULE) entry.byCategory.applied += 1;
+      else if (cat === LEARNING_CATEGORIES.EXCEPTION_WITH_RATIONALE) entry.byCategory.exception += 1;
+      else entry.byCategory.uncategorized += 1;
+    }
+  }
+
+  for (const [candidate, entry] of skillCandidates) {
+    if (entry.weighted >= 2) {  // Threshold: ≥2 weighted learnings → flag
+      const bc = entry.byCategory;
+      const detail = `${bc.discovered} discovered-new-pattern, ${bc.uncategorized} uncategorized, ${bc.applied} applied-existing (excluded), ${bc.exception} exception (excluded)`;
+      findings.push({
+        severity: 'INFO',
+        category: 'SKILL_CANDIDATE',
+        skill: candidate,
+        message: `${entry.weighted} of ${entry.total} learnings reference "${candidate}" as a promotion candidate but no such skill exists — consider creating it (${detail})`,
+      });
+    }
+  }
+
+  // ─── Summary ───
+  const summary = {
+    skills_audited: skillFiles.length,
+    learnings_scanned: learningsFiles.length,
+    error_count: findings.filter((f) => f.severity === 'ERROR').length,
+    warn_count: findings.filter((f) => f.severity === 'WARN').length,
+    info_count: findings.filter((f) => f.severity === 'INFO').length,
+  };
+
+  return { findings, summary };
+}
+
+module.exports = {
+  auditSkills,
+  // AU-001 (#159): exported for unit tests + future consumers
+  classifyPathCandidate,
+  collectPathCandidates,
+  globMatch,
+  VERDICTS,
+  KNOWN_PATH_PREFIXES,
+  KNOWN_FILE_EXTENSIONS,
+};