@rune-kit/rune 2.10.0 → 2.12.0

package/compiler/doctor.js

@@ -2,6 +2,7 @@
  * Doctor — Validates compiled output
  *
  * Checks: files exist, cross-references resolve, layer discipline, source freshness.
+ * Mesh checks: reciprocal connections, version suggestions, required sections.
  */
 
 import { existsSync } from 'node:fs';
@@ -454,6 +455,241 @@ async function checkOrgTemplates(_runeRoot, config) {
   return errors;
 }
 
+/**
+ * Check mesh integrity: reciprocal connections, version suggestions, required sections
+ *
+ * @param {string} runeRoot - path to Rune source root
+ * @returns {Promise<object>} mesh check results
+ */
+export async function checkMeshIntegrity(runeRoot) {
+  const results = {
+    checks: [],
+    warnings: [],
+    errors: [],
+    stats: { skills: 0, connections: 0, missingReciprocals: 0 },
+  };
+
+  const skillsDir = path.join(runeRoot, 'skills');
+  if (!existsSync(skillsDir)) {
+    results.errors.push('skills/ directory not found');
+    return results;
+  }
+
+  // Step 1: Parse all skills
+  const skills = new Map(); // name → { calls: [], calledBy: [], version, sections }
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (!existsSync(skillFile)) continue;
+
+    const content = await readFile(skillFile, 'utf-8');
+    const parsed = parseSkillConnections(content, entry.name);
+    skills.set(entry.name, parsed);
+  }
+
+  results.stats.skills = skills.size;
+
+  // Step 2: Validate reciprocals
+  const missingReciprocals = [];
+
+  for (const [name, skill] of skills) {
+    for (const called of skill.calls) {
+      const targetSkill = skills.get(called.skill);
+      if (!targetSkill) continue; // External skill or L4 pack
+
+      // Check if target acknowledges this caller
+      const acknowledges = targetSkill.calledBy.some((c) => c.skill === name);
+      if (!acknowledges) {
+        missingReciprocals.push({
+          caller: name,
+          callee: called.skill,
+          reason: called.reason,
+        });
+      }
+    }
+    results.stats.connections += skill.calls.length;
+  }
+
+  results.stats.missingReciprocals = missingReciprocals.length;
+
+  if (missingReciprocals.length === 0) {
+    results.checks.push({ name: 'Reciprocal connections', status: 'pass' });
+  } else {
+    results.checks.push({
+      name: 'Reciprocal connections',
+      status: 'warn',
+      detail: `${missingReciprocals.length} missing`,
+    });
+    // Group by callee for cleaner output
+    const byCallee = {};
+    for (const m of missingReciprocals) {
+      if (!byCallee[m.callee]) byCallee[m.callee] = [];
+      byCallee[m.callee].push(m.caller);
+    }
+    for (const [callee, callers] of Object.entries(byCallee)) {
+      results.warnings.push(`${callee}: missing callers in Called By: ${callers.join(', ')}`);
+    }
+  }
+
+  // Step 3: Check version maturity
+  const matureButLow = [];
+  for (const [name, skill] of skills) {
+    if (!skill.version) continue;
+    const [major, minor] = skill.version.split('.').map(Number);
+    // Suggest 1.0 if version is 0.8+ and has all required sections
+    if (major === 0 && minor >= 8 && skill.hasAllSections) {
+      matureButLow.push({ name, version: skill.version });
+    }
+  }
+
+  if (matureButLow.length === 0) {
+    results.checks.push({ name: 'Version maturity', status: 'pass' });
+  } else {
+    results.checks.push({
+      name: 'Version maturity',
+      status: 'warn',
+      detail: `${matureButLow.length} skills ready for 1.0`,
+    });
+    for (const s of matureButLow) {
+      results.warnings.push(`${s.name} v${s.version}: mature skill, consider promoting to 1.0`);
+    }
+  }
+
+  // Step 4: Check required sections
+  const requiredSections = ['Sharp Edges', 'Done When', 'Cost Profile'];
+  const missingSections = [];
+
+  for (const [name, skill] of skills) {
+    const missing = requiredSections.filter((s) => !skill.sections.includes(s));
+    if (missing.length > 0) {
+      missingSections.push({ name, missing });
+    }
+  }
+
+  if (missingSections.length === 0) {
+    results.checks.push({ name: 'Required sections', status: 'pass' });
+  } else {
+    results.checks.push({
+      name: 'Required sections',
+      status: 'warn',
+      detail: `${missingSections.length} skills incomplete`,
+    });
+    for (const s of missingSections) {
+      results.warnings.push(`${s.name}: missing sections: ${s.missing.join(', ')}`);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Parse skill connections from SKILL.md content
+ */
+function parseSkillConnections(content, skillName) {
+  const result = {
+    name: skillName,
+    calls: [],
+    calledBy: [],
+    version: null,
+    sections: [],
+    hasAllSections: false,
+  };
+
+  // Extract version from frontmatter
+  const versionMatch = content.match(/version:\s*["']?([\d.]+)["']?/);
+  if (versionMatch) {
+    result.version = versionMatch[1];
+  }
+
+  // Extract Calls section
+  const callsMatch = content.match(/## Calls \(outbound\)\s*\n([\s\S]*?)(?=\n## |\n---|Z)/);
+  if (callsMatch) {
+    const lines = callsMatch[1].split('\n');
+    for (const line of lines) {
+      // Match patterns like: - `scout` (L2): scan codebase
+      // Or: - scout (L2): scan codebase
+      const match = line.match(/^-\s*`?([a-z][\w-]*)`?\s*\(L\d\)/i);
+      if (match) {
+        const skillRef = match[1].toLowerCase();
+        const reason = line
+          .replace(match[0], '')
+          .replace(/^[:\s-]+/, '')
+          .trim();
+        result.calls.push({ skill: skillRef, reason });
+      }
+    }
+  }
+
+  // Extract Called By section
+  const calledByMatch = content.match(/## Called By \(inbound\)\s*\n([\s\S]*?)(?=\n## |\n---|Z)/);
+  if (calledByMatch) {
+    const lines = calledByMatch[1].split('\n');
+    for (const line of lines) {
+      const match = line.match(/^-\s*`?([a-z][\w-]*)`?\s*\(L\d\)/i);
+      if (match) {
+        const skillRef = match[1].toLowerCase();
+        result.calledBy.push({ skill: skillRef });
+      }
+    }
+  }
+
+  // Check for required sections
+  const sectionPatterns = [
+    { name: 'Sharp Edges', pattern: /## Sharp Edges/ },
+    { name: 'Done When', pattern: /## Done When/ },
+    { name: 'Cost Profile', pattern: /## Cost Profile/ },
+    { name: 'Returns', pattern: /## Returns/ },
+  ];
+
+  for (const { name, pattern } of sectionPatterns) {
+    if (pattern.test(content)) {
+      result.sections.push(name);
+    }
+  }
+
+  result.hasAllSections = sectionPatterns.every(({ name }) => result.sections.includes(name));
+
+  return result;
+}
+
+/**
+ * Format mesh results for console output
+ */
+export function formatMeshResults(results) {
+  const lines = [];
+  lines.push(`\n  Mesh Integrity Check`);
+  lines.push(`  Skills: ${results.stats.skills} | Connections: ${results.stats.connections}`);
+  lines.push('');
+
+  for (const check of results.checks) {
+    const icon = check.status === 'pass' ? '✓' : check.status === 'warn' ? '!' : '✗';
+    const detail = check.detail ? ` (${check.detail})` : '';
+    lines.push(`  [${icon}] ${check.name}${detail}`);
+  }
+
+  if (results.warnings.length > 0) {
+    lines.push('');
+    for (const w of results.warnings) {
+      lines.push(`  ⚠ ${w}`);
+    }
+  }
+
+  if (results.errors.length > 0) {
+    lines.push('');
+    for (const e of results.errors) {
+      lines.push(`  ✗ ${e}`);
+    }
+  }
+
+  const healthy = results.errors.length === 0 && results.warnings.length === 0;
+  lines.push('');
+  lines.push(healthy ? '  ✓ Mesh is healthy' : `  ! Mesh has ${results.warnings.length} warnings`);
+
+  return lines.join('\n');
+}
+
 /**
  * Format doctor results for console output
  */

package/contexts/dev.md

@@ -1,34 +1,34 @@
-# Development Mode
-
-Behavioral context for active coding sessions. Prioritize action over analysis.
-
-## Principles
-
-- **Code first, explain after** — show working code, not paragraphs about what you'll do
-- **Working → Right → Clean** — get it running, make it correct, then refine
-- **Bias toward action** — if the path is 80% clear, start coding rather than analyzing further
-
-## Tool Priority
-
-```
-HIGH:    Edit, Write, Bash (run tests/build)
-MEDIUM:  Read (targeted files), Grep (specific patterns)
-LOW:     Glob (broad search), WebSearch (external docs)
-```
-
-## Behavioral Rules
-
-1. Read the file BEFORE editing — never guess at existing code
-2. Run tests after every meaningful change
-3. If stuck for >2 iterations on the same error, switch strategy:
-   - Try a different approach rather than debugging deeper
-   - Use `rune:debug` for structured root cause analysis
-4. Keep explanations to 1-2 sentences between code blocks
-5. Commit working increments — don't batch everything into one giant change
-
-## Anti-Patterns
-
-- Lengthy analysis before writing a single line of code
-- Reading 10+ files "for context" when 2-3 would suffice
-- Explaining what you're about to do instead of doing it
-- Over-engineering the first pass (violates Working → Right → Clean)
+# Development Mode
+
+Behavioral context for active coding sessions. Prioritize action over analysis.
+
+## Principles
+
+- **Code first, explain after** — show working code, not paragraphs about what you'll do
+- **Working → Right → Clean** — get it running, make it correct, then refine
+- **Bias toward action** — if the path is 80% clear, start coding rather than analyzing further
+
+## Tool Priority
+
+```
+HIGH:    Edit, Write, Bash (run tests/build)
+MEDIUM:  Read (targeted files), Grep (specific patterns)
+LOW:     Glob (broad search), WebSearch (external docs)
+```
+
+## Behavioral Rules
+
+1. Read the file BEFORE editing — never guess at existing code
+2. Run tests after every meaningful change
+3. If stuck for >2 iterations on the same error, switch strategy:
+   - Try a different approach rather than debugging deeper
+   - Use `rune:debug` for structured root cause analysis
+4. Keep explanations to 1-2 sentences between code blocks
+5. Commit working increments — don't batch everything into one giant change
+
+## Anti-Patterns
+
+- Lengthy analysis before writing a single line of code
+- Reading 10+ files "for context" when 2-3 would suffice
+- Explaining what you're about to do instead of doing it
+- Over-engineering the first pass (violates Working → Right → Clean)

package/contexts/research.md

@@ -1,43 +1,43 @@
-# Research Mode
-
-Behavioral context for investigation, exploration, and understanding. Prioritize breadth and accuracy over speed.
-
-## Principles
-
-- **Read widely before concluding** — check 3+ sources before forming an opinion
-- **Map before moving** — understand the full landscape before recommending a path
-- **Evidence over intuition** — every claim should reference a file, doc, or search result
-
-## Tool Priority
-
-```
-HIGH:    Grep, Glob, Read, WebSearch, WebFetch
-MEDIUM:  Bash (non-destructive: git log, dependency checks)
-LOW:     Edit, Write (only for saving findings)
-```
-
-## Investigation Framework
-
-1. **Define the question** — what exactly are we trying to learn?
-2. **Internal scan** — search the codebase first (Grep, Glob, Read)
-3. **External lookup** — check docs, changelogs, GitHub issues (WebSearch, WebFetch)
-4. **Cross-reference** — validate findings against 2+ sources
-5. **Synthesize** — present findings with confidence levels:
-   - **Confirmed**: found in code/docs, verified
-   - **Likely**: strong evidence but not 100% confirmed
-   - **Uncertain**: limited evidence, needs more investigation
-
-## Behavioral Rules
-
-1. Never modify code in research mode — read-only exploration
-2. Present findings in structured format (tables, bullet points)
-3. Include file paths and line numbers for all code references
-4. Flag contradictions between sources rather than picking one silently
-5. Estimate scope/effort when the research is for planning purposes
-
-## Anti-Patterns
-
-- Jumping to a solution after reading one file
-- Modifying code "while we're here" during research
-- Presenting opinions as facts without evidence trail
-- Stopping research early because the first answer looks plausible
+# Research Mode
+
+Behavioral context for investigation, exploration, and understanding. Prioritize breadth and accuracy over speed.
+
+## Principles
+
+- **Read widely before concluding** — check 3+ sources before forming an opinion
+- **Map before moving** — understand the full landscape before recommending a path
+- **Evidence over intuition** — every claim should reference a file, doc, or search result
+
+## Tool Priority
+
+```
+HIGH:    Grep, Glob, Read, WebSearch, WebFetch
+MEDIUM:  Bash (non-destructive: git log, dependency checks)
+LOW:     Edit, Write (only for saving findings)
+```
+
+## Investigation Framework
+
+1. **Define the question** — what exactly are we trying to learn?
+2. **Internal scan** — search the codebase first (Grep, Glob, Read)
+3. **External lookup** — check docs, changelogs, GitHub issues (WebSearch, WebFetch)
+4. **Cross-reference** — validate findings against 2+ sources
+5. **Synthesize** — present findings with confidence levels:
+   - **Confirmed**: found in code/docs, verified
+   - **Likely**: strong evidence but not 100% confirmed
+   - **Uncertain**: limited evidence, needs more investigation
+
+## Behavioral Rules
+
+1. Never modify code in research mode — read-only exploration
+2. Present findings in structured format (tables, bullet points)
+3. Include file paths and line numbers for all code references
+4. Flag contradictions between sources rather than picking one silently
+5. Estimate scope/effort when the research is for planning purposes
+
+## Anti-Patterns
+
+- Jumping to a solution after reading one file
+- Modifying code "while we're here" during research
+- Presenting opinions as facts without evidence trail
+- Stopping research early because the first answer looks plausible

package/contexts/review.md

@@ -1,55 +1,55 @@
-# Review Mode
-
-Behavioral context for evaluating code quality, correctness, and security. Prioritize thoroughness and constructive feedback.
-
-## Principles
-
-- **Read everything in scope** — review the full diff, not just highlighted sections
-- **Severity matters** — distinguish blockers from suggestions, label clearly
-- **Constructive over critical** — pair every issue with a concrete fix or alternative
-
-## Tool Priority
-
-```
-HIGH:    Read (full files), Grep (pattern search), Bash (git diff)
-MEDIUM:  Glob (find related files), WebSearch (verify best practices)
-LOW:     Edit, Write (only for review notes/reports)
-```
-
-## Review Dimensions
-
-Check each dimension systematically:
-
-| Dimension | What to Check |
-|-----------|--------------|
-| **Correctness** | Logic errors, off-by-one, null handling, async/await misuse |
-| **Security** | OWASP patterns, secret exposure, input validation |
-| **Performance** | N+1 queries, unnecessary re-renders, missing indexes |
-| **Maintainability** | Naming clarity, function length, coupling, duplication |
-| **Completeness** | Error handling, edge cases, loading/error states, tests |
-| **Conventions** | Project patterns, naming style, file organization |
-
-## Severity Scale
-
-```
-BLOCK     — Must fix before merge (bugs, security, data loss risk)
-HIGH      — Should fix before merge (logic issues, missing validation)
-MEDIUM    — Fix soon (code quality, minor performance)
-LOW       — Nice to have (style preference, minor improvements)
-PRAISE    — Highlight good patterns worth replicating
-```
-
-## Behavioral Rules
-
-1. Always include at least one PRAISE item — acknowledge what's done well
-2. Group findings by file, then by severity (BLOCK first)
-3. Show the problematic code AND the suggested fix side-by-side
-4. Check git blame for context — is this new code or existing?
-5. Verify the fix actually works before suggesting it
-
-## Anti-Patterns
-
-- Drive-by "LGTM" without reading the code
-- Nitpicking style while missing logic bugs
-- Suggesting rewrites when the code is correct and readable
-- Reviewing only the files explicitly mentioned, ignoring related changes
+# Review Mode
+
+Behavioral context for evaluating code quality, correctness, and security. Prioritize thoroughness and constructive feedback.
+
+## Principles
+
+- **Read everything in scope** — review the full diff, not just highlighted sections
+- **Severity matters** — distinguish blockers from suggestions, label clearly
+- **Constructive over critical** — pair every issue with a concrete fix or alternative
+
+## Tool Priority
+
+```
+HIGH:    Read (full files), Grep (pattern search), Bash (git diff)
+MEDIUM:  Glob (find related files), WebSearch (verify best practices)
+LOW:     Edit, Write (only for review notes/reports)
+```
+
+## Review Dimensions
+
+Check each dimension systematically:
+
+| Dimension | What to Check |
+|-----------|--------------|
+| **Correctness** | Logic errors, off-by-one, null handling, async/await misuse |
+| **Security** | OWASP patterns, secret exposure, input validation |
+| **Performance** | N+1 queries, unnecessary re-renders, missing indexes |
+| **Maintainability** | Naming clarity, function length, coupling, duplication |
+| **Completeness** | Error handling, edge cases, loading/error states, tests |
+| **Conventions** | Project patterns, naming style, file organization |
+
+## Severity Scale
+
+```
+BLOCK     — Must fix before merge (bugs, security, data loss risk)
+HIGH      — Should fix before merge (logic issues, missing validation)
+MEDIUM    — Fix soon (code quality, minor performance)
+LOW       — Nice to have (style preference, minor improvements)
+PRAISE    — Highlight good patterns worth replicating
+```
+
+## Behavioral Rules
+
+1. Always include at least one PRAISE item — acknowledge what's done well
+2. Group findings by file, then by severity (BLOCK first)
+3. Show the problematic code AND the suggested fix side-by-side
+4. Check git blame for context — is this new code or existing?
+5. Verify the fix actually works before suggesting it
+
+## Anti-Patterns
+
+- Drive-by "LGTM" without reading the code
+- Nitpicking style while missing logic bugs
+- Suggesting rewrites when the code is correct and readable
+- Reviewing only the files explicitly mentioned, ignoring related changes