pan-wizard 3.5.1 → 3.7.10

package/package.json

@@ -1,66 +1,67 @@
-{
-  "name": "pan-wizard",
-  "version": "3.5.1",
-  "description": "A lightweight workflow automation and context engineering system for Claude Code, OpenCode, Gemini CLI, Codex, and Copilot CLI.",
-  "bin": {
-    "pan-wizard": "bin/install.js"
-  },
-  "files": [
-    "bin",
-    "commands",
-    "pan-wizard-core",
-    "agents",
-    "hooks/dist",
-    "scripts",
-    "assets"
-  ],
-  "keywords": [
-    "claude",
-    "claude-code",
-    "ai",
-    "workflow-automation",
-    "context-engineering",
-    "project-automation",
-    "gemini",
-    "gemini-cli",
-    "codex",
-    "codex-cli",
-    "copilot",
-    "copilot-cli",
-    "github-copilot"
-  ],
-  "author": "PAN Wizard Contributors",
-  "contributors": [
-    {
-      "name": "oharms",
-      "url": "https://github.com/oharms"
-    }
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/oharms/PanWizard.git"
-  },
-  "homepage": "https://github.com/oharms/PanWizard#readme",
-  "bugs": {
-    "url": "https://github.com/oharms/PanWizard/issues"
-  },
-  "engines": {
-    "node": ">=16.7.0"
-  },
-  "devDependencies": {
-    "@playwright/test": "^1.58.2",
-    "@vscode/test-electron": "^2.5.2",
-    "esbuild": "^0.24.0"
-  },
-  "scripts": {
-    "build:hooks": "node scripts/build-hooks.js",
-    "prepublishOnly": "npm run build:hooks",
-    "test": "node --test tests/*.test.cjs",
-    "test:scenarios": "node --test tests/scenarios/*.test.cjs",
-    "test:all": "node --test tests/*.test.cjs tests/scenarios/*.test.cjs",
-    "test:e2e": "node --test tests/scenarios/*.test.cjs",
-    "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
-    "test:watch": "node --test --watch tests/*.test.cjs"
-  }
-}
+{
+  "name": "pan-wizard",
+  "version": "3.7.10",
+  "description": "A lightweight workflow automation and context engineering system for Claude Code, OpenCode, Gemini CLI, Codex, and Copilot CLI.",
+  "bin": {
+    "pan-wizard": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "pan-wizard-core",
+    "agents",
+    "hooks/dist",
+    "scripts",
+    "assets"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "workflow-automation",
+    "context-engineering",
+    "project-automation",
+    "gemini",
+    "gemini-cli",
+    "codex",
+    "codex-cli",
+    "copilot",
+    "copilot-cli",
+    "github-copilot"
+  ],
+  "author": "PAN Wizard Contributors",
+  "contributors": [
+    {
+      "name": "oharms",
+      "url": "https://github.com/oharms"
+    }
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oharms/PanWizard.git"
+  },
+  "homepage": "https://github.com/oharms/PanWizard#readme",
+  "bugs": {
+    "url": "https://github.com/oharms/PanWizard/issues"
+  },
+  "engines": {
+    "node": ">=16.7.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@vscode/test-electron": "^2.5.2",
+    "esbuild": "^0.24.0"
+  },
+  "scripts": {
+    "build:hooks": "node scripts/build-hooks.js",
+    "release:check": "node scripts/release-check.js",
+    "prepublishOnly": "node scripts/release-check.js",
+    "test": "node --test tests/*.test.cjs",
+    "test:scenarios": "node --test tests/scenarios/*.test.cjs",
+    "test:all": "node --test tests/*.test.cjs tests/scenarios/*.test.cjs",
+    "test:e2e": "node --test tests/scenarios/*.test.cjs",
+    "test:vscode": "npx playwright test --config tests/e2e/playwright.config.mjs",
+    "test:watch": "node --test --watch tests/*.test.cjs"
+  }
+}

package/pan-wizard-core/bin/lib/commands.cjs

@@ -379,6 +379,11 @@ function runCommitSafetyChecks(cwd, config, force) {
 function cmdCommit(cwd, message, files, raw, amend, opts) {
   const commitType = opts && opts.type;
   const force = opts && opts.force;
+  // P-EXP-001 follow-up (v3.7.10): when failOnError is true, commit_failed
+  // exits non-zero so callers (especially autonomous loops) detect the silent-
+  // failure case where git refused (e.g. missing identity) and the loop would
+  // otherwise keep going thinking the artifact landed.
+  const failOnError = opts && opts.failOnError;
 
   if (!isGitRepo(cwd)) {
     output({ committed: false, hash: null, reason: 'not_a_git_repo', hint: 'Run git init to initialize a repository' }, raw, 'not a git repo');
@@ -425,6 +430,9 @@ function cmdCommit(cwd, message, files, raw, amend, opts) {
       output({ committed: false, hash: null, reason: 'nothing_to_commit' }, raw, 'nothing');
       return;
     }
+    if (failOnError) {
+      error('commit_failed: ' + (commitResult.stderr || 'unknown git error').trim());
+    }
     output({ committed: false, hash: null, reason: 'commit_failed', error: commitResult.stderr }, raw, 'failed');
     return;
   }

package/pan-wizard-core/bin/lib/config.cjs

@@ -52,6 +52,7 @@ function buildConfigDefaults(hasBraveSearch, userDefaults) {
       plan_check: true,
       verifier: true,
       nyquist_validation: false,
+      phase_record_compact: false,
     },
     parallelization: true,
     brave_search: hasBraveSearch,
@@ -422,17 +423,27 @@ function cmdStandardsRecommend(cwd, raw) {
   if (/\b(enterprise|togaf|architecture\s*governance|compliance)\b/.test(lower)) detectedTypes.push('enterprise');
   if (/\b(cli|command.line|terminal|shell|argv)\b/.test(lower)) detectedTypes.push('cli');
 
-  if (detectedTypes.length === 0) detectedTypes.push('general');
+  const explicitlyDetected = detectedTypes.length > 0;
+  if (!explicitlyDetected) detectedTypes.push('general');
 
   const seen = new Set();
   const recommendations = [];
   for (const type of detectedTypes) {
     const recs = STANDARDS_RECOMMENDATIONS[type] || [];
+    let perTypeIndex = 0;
     for (const id of recs) {
       if (seen.has(id)) continue;
       seen.add(id);
       const s = STANDARDS_CATALOG[id];
-      recommendations.push({ id, name: s.name, reason: type + ' project detected', priority: recommendations.length < 3 ? 'high' : 'medium' });
+      const isHigh = explicitlyDetected && type !== 'general' && perTypeIndex === 0;
+      recommendations.push({
+        id,
+        name: s.name,
+        reason: type + ' project detected',
+        priority: isHigh ? 'high' : 'medium',
+        source_type: type,
+      });
+      perTypeIndex += 1;
     }
   }
 

package/pan-wizard-core/bin/lib/context-budget.cjs

@@ -21,6 +21,51 @@ function estimateTokens(text) {
   return Math.ceil(text.length / CHARS_PER_TOKEN);
 }
 
+/**
+ * Estimate a relevance signal for per-phase markdown content (P-RES-002).
+ *
+ * Per Chroma's "Context Rot" research (Hong & Huber, July 2025): a single
+ * semantically-similar-but-irrelevant distractor degrades performance even
+ * at modest context sizes. Distractor density matters more than token count.
+ *
+ * Computing TRUE topic-relevance requires embeddings or keyword analysis
+ * we can't do cheaply at zero deps. This v0 heuristic reports a simpler
+ * signal: structure-vs-content ratio. Markdown files heavy on headers,
+ * separators, empty bullet lists, and placeholder text are LESS dense in
+ * actual signal than files of equal length with concrete prose. The ratio
+ * isn't true distractor density but is correlated with it for the
+ * "thin/template-only context" failure mode.
+ *
+ * Returns ratio in [0, 1] where 1 = all content lines, 0 = all structure.
+ * Returns null if not enough lines to compute meaningfully.
+ *
+ * @param {string} text
+ * @returns {number|null}
+ */
+function estimateRelevanceRatio(text) {
+  if (!text) return null;
+  const lines = text.split(/\r?\n/);
+  if (lines.length < 5) return null;
+  let contentLines = 0;
+  let totalLines = 0;
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line) continue;                              // skip blank
+    totalLines++;
+    if (/^#{1,6}\s/.test(line)) continue;             // skip header
+    if (/^[-*_]{3,}$/.test(line)) continue;           // skip separator
+    if (/^[-*]\s*$/.test(line)) continue;             // skip empty bullet
+    if (/^[-*]\s*\[\s*[\]x_]\s*\]\s*$/.test(line)) continue; // empty checkbox
+    if (/^\|\s*-+\s*\|/.test(line)) continue;         // table separator row
+    if (/^>\s*$/.test(line)) continue;                // empty blockquote
+    if (line.length < 10) continue;                   // very short — likely scaffolding
+    if (/^(TODO|TBD|FIXME|placeholder|todo|tbd|fixme|placeholder|coming soon)\b/i.test(line)) continue;
+    contentLines++;
+  }
+  if (totalLines === 0) return null;
+  return Math.round((contentLines / totalLines) * 1000) / 1000;
+}
+
 /**
  * Compute context budget for the current project state.
  * @param {string} cwd - Project root directory
@@ -101,6 +146,32 @@ function cmdContextBudget(cwd, raw) {
     recommendation = `Within budget. ~${additionalPlans} more plans could fit before degradation.`;
   }
 
+  // P-RES-002 signal: structure-vs-content ratio for per-phase markdown.
+  // High structure (lots of empty bullets, headers, placeholders) suggests
+  // the per-phase context is thin/templatey rather than substantive — a
+  // proxy for "context that's wasting tokens on filler."
+  let relevanceSignal = null;
+  if (phaseDir) {
+    const fullPhasePath = path.join(cwd, phaseDir);
+    const samples = [];
+    for (const fname of ['research.md', 'context.md']) {
+      const candidate = path.join(fullPhasePath, fname);
+      const content = safeReadFile(candidate);
+      if (content) {
+        const ratio = estimateRelevanceRatio(content);
+        if (ratio !== null) samples.push({ file: toPosix(path.join(phaseDir, fname)), ratio });
+      }
+    }
+    if (samples.length > 0) {
+      const avg = samples.reduce((a, s) => a + s.ratio, 0) / samples.length;
+      relevanceSignal = {
+        avg_ratio: Math.round(avg * 1000) / 1000,
+        samples,
+        note: 'P-RES-002 v0 heuristic — structure/content ratio. <0.4 suggests thin per-phase context (heavy on headers + empty buckets + placeholders).',
+      };
+    }
+  }
+
   // E-8: cache metrics — surface how much of the total context would be
   // served from prompt cache when Opus 4.7 cache_control is active.
   const { buildCachedContext } = require('./core.cjs');
@@ -141,6 +212,7 @@ function cmdContextBudget(cwd, raw) {
     contextWindow: CONTEXT_WINDOW,
     budgetUtilization: Math.round(utilization * 1000) / 1000,
     cache,
+    relevanceSignal,
     recommendation,
   };
 
@@ -174,4 +246,5 @@ function cmdContextBudget(cwd, raw) {
 module.exports = {
   cmdContextBudget,
   estimateTokens,
+  estimateRelevanceRatio,
 };

package/pan-wizard-core/bin/lib/core.cjs

@@ -48,6 +48,7 @@ const COST_MULTIPLIERS = { reasoning: 15, mid: 3, fast: 1 };
 // ─── Model Profile Table ─────────────────────────────────────────────────────
 
 const MODEL_PROFILES = {
+  // Original planning/execution agents (pre-v3.0)
   'pan-planner':              { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
   'pan-roadmapper':           { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
   'pan-executor':             { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
@@ -60,6 +61,18 @@ const MODEL_PROFILES = {
   'pan-plan-checker':         { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
   'pan-integration-checker':  { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
   'pan-reviewer':             { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // Spec B v2 agents (v3.0–v3.4) — added v3.7.5 to close MODEL_PROFILES drift
+  'pan-conductor':            { quality: 'reasoning', balanced: 'reasoning', budget: 'mid' },
+  'pan-counterfactual':       { quality: 'reasoning', balanced: 'mid',      budget: 'mid' },
+  'pan-hardener':             { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-meta-reviewer':        { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-knowledge':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-previewer':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // v3.5 agents
+  'pan-optimizer':            { quality: 'reasoning', balanced: 'mid',      budget: 'fast' },
+  'pan-distiller':            { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
+  // v3.7.0 self-improvement loop — observation-only watchdog
+  'pan-experiment-runner':    { quality: 'reasoning', balanced: 'fast',     budget: 'fast' },
 };
 
 // ─── Output helpers ───────────────────────────────────────────────────────────

package/pan-wizard-core/bin/lib/doc-lint/frontmatter.js

@@ -0,0 +1,270 @@
+'use strict';
+/**
+ * frontmatter.js — minimal YAML-ish frontmatter parser.
+ *
+ * Supports the subset documented in DESIGN_SPEC.md §"YAML subset":
+ *   - Scalars: strings (quoted or bare), numbers, booleans, null
+ *   - Flow lists: [a, b, c]
+ *   - Block maps: key: value (one per line)
+ *   - Comments: # ... (skipped)
+ *
+ * Anything beyond this subset → error code 'frontmatter-malformed'.
+ *
+ * Returns: {data, bodyStart, errors}
+ *   data       — parsed object (empty {} if no frontmatter)
+ *   bodyStart  — line number (1-indexed) where the body starts (after closing ---)
+ *                Used for line-number arithmetic in violation reports.
+ *   errors     — array of {line, message} for parse problems (NOT validation —
+ *                that's validate.js's job)
+ */
+
+const FENCE = '---';
+
+function parseFrontmatter(text) {
+  if (text == null) return { data: {}, bodyStart: 1, errors: [] };
+
+  const lines = text.split(/\r?\n/);
+  if (lines.length === 0 || lines[0] !== FENCE) {
+    // No frontmatter. Body starts at line 1.
+    return { data: {}, bodyStart: 1, errors: [], hasFrontmatter: false };
+  }
+
+  // Find closing fence
+  let closingIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === FENCE) {
+      closingIndex = i;
+      break;
+    }
+  }
+
+  if (closingIndex === -1) {
+    return {
+      data: {},
+      bodyStart: 1,
+      errors: [{ line: 1, message: 'frontmatter opening --- has no matching closing ---' }],
+      hasFrontmatter: true,
+    };
+  }
+
+  const fmLines = lines.slice(1, closingIndex);
+  const result = parseFrontmatterBlock(fmLines);
+
+  return {
+    data: result.data,
+    bodyStart: closingIndex + 2, // 1-indexed line AFTER the closing ---
+    errors: result.errors,
+    hasFrontmatter: true,
+  };
+}
+
+function parseFrontmatterBlock(lines) {
+  const data = {};
+  const errors = [];
+
+  // Extended after dogfood gate (see .planning/optimization/traces/.../trace.jsonl event 2026-04-27T11:50:00Z):
+  // Block-style lists are the dominant real-world format. The DESIGN_SPEC originally
+  // scoped them out — that decision was wrong. Block-list support added per deviation R1.
+
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 2; // 1-indexed in source file (line 1 is opening ---)
+    let line = lines[i];
+
+    // Strip trailing comments
+    line = stripTrailingComment(line);
+
+    // Skip blank/comment-only lines
+    if (line.trim() === '') continue;
+
+    // Match `key:` (no value) — start of a block list or block map
+    const blockKeyMatch = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*$/);
+    if (blockKeyMatch) {
+      const key = blockKeyMatch[1];
+
+      // Look ahead: collect subsequent lines that are list items ("  - x") or
+      // sub-map entries ("  k: v") indented under this key. Stop at next top-level
+      // key (no leading whitespace) or end of block.
+      const childLines = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const next = lines[j];
+        if (next.trim() === '' || next.trim().startsWith('#')) { j++; continue; }
+        // Top-level key (no indent) ends the child block
+        if (/^[A-Za-z_]/.test(next)) break;
+        // Indented line — accumulate
+        childLines.push({ raw: next, line: j + 2 });
+        j++;
+      }
+
+      // Detect: is this a block list (- items) or a block map (key: val)?
+      const looksList = childLines.length > 0 && childLines.every(c => /^\s+-\s+/.test(c.raw));
+      if (looksList) {
+        const items = [];
+        for (const cl of childLines) {
+          const itemMatch = cl.raw.match(/^\s+-\s+(.*)$/);
+          if (!itemMatch) {
+            errors.push({ line: cl.line, message: `expected "- value" in block list, got: ${JSON.stringify(cl.raw)}` });
+            continue;
+          }
+          const itemRaw = stripTrailingComment(itemMatch[1]).trim();
+          const parsed = parseScalarOrList(itemRaw, cl.line);
+          if (parsed.error) {
+            errors.push({ line: cl.line, message: `in list item: ${parsed.error}` });
+            continue;
+          }
+          items.push(parsed.value);
+        }
+        if (key in data) {
+          errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+        } else {
+          data[key] = items;
+        }
+        i = j - 1; // resume after the block
+        continue;
+      }
+      // Block map shape: not supported in v0.1, but don't error — treat the
+      // key as null-valued and let validation handle it.
+      if (childLines.length > 0) {
+        // Block-style maps are out of scope per DESIGN_SPEC. Surface a warning
+        // rather than a crash so the rest of the file still validates.
+        errors.push({ line: lineNum, message: `block-map values not supported in v0.1 for key "${key}" (use a flow map or scalar)` });
+        i = j - 1;
+        continue;
+      }
+      // No child lines → just an empty value
+      if (key in data) {
+        errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      } else {
+        data[key] = null;
+      }
+      continue;
+    }
+
+    // Match `key: value` (scalar / flow list / etc.)
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.*)$/);
+    if (!m) {
+      errors.push({ line: lineNum, message: `expected "key: value", got: ${JSON.stringify(line)}` });
+      continue;
+    }
+
+    const key = m[1];
+    const rawValue = m[2];
+
+    if (key in data) {
+      errors.push({ line: lineNum, message: `duplicate key "${key}"` });
+      continue;
+    }
+
+    const parsed = parseScalarOrList(rawValue, lineNum);
+    if (parsed.error) {
+      errors.push({ line: lineNum, message: parsed.error });
+      continue;
+    }
+    data[key] = parsed.value;
+  }
+
+  return { data, errors };
+}
+
+function stripTrailingComment(line) {
+  // Naive: strip from first # not inside quotes. PAN frontmatter doesn't put
+  // # in values, so this is safe for our subset. If a user does, they'll see
+  // a frontmatter-malformed error and can quote it.
+  const inSingle = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === "'") q++;
+    return q % 2 === 1;
+  };
+  const inDouble = (s, idx) => {
+    let q = 0;
+    for (let j = 0; j < idx; j++) if (s[j] === '"') q++;
+    return q % 2 === 1;
+  };
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '#' && !inSingle(line, i) && !inDouble(line, i)) {
+      return line.slice(0, i).trimEnd();
+    }
+  }
+  return line;
+}
+
+function parseScalarOrList(raw, lineNum) {
+  const trimmed = raw.trim();
+
+  if (trimmed === '') return { value: null };
+
+  // Flow list: [a, b, c]
+  if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === '') return { value: [] };
+    const items = splitFlowItems(inner);
+    const parsedItems = [];
+    for (const item of items) {
+      const sub = parseScalarOrList(item, lineNum);
+      if (sub.error) return { error: `in list: ${sub.error}` };
+      parsedItems.push(sub.value);
+    }
+    return { value: parsedItems };
+  }
+
+  if (trimmed.startsWith('{')) {
+    return { error: `inline maps not supported in v0.1 (got ${JSON.stringify(trimmed)})` };
+  }
+
+  // Quoted strings
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    if (trimmed.length < 2) return { error: 'unterminated quoted string' };
+    return { value: trimmed.slice(1, -1) };
+  }
+
+  // Bare keywords
+  if (trimmed === 'true') return { value: true };
+  if (trimmed === 'false') return { value: false };
+  if (trimmed === 'null' || trimmed === '~') return { value: null };
+
+  // Numbers
+  if (/^-?\d+$/.test(trimmed)) return { value: parseInt(trimmed, 10) };
+  if (/^-?\d+\.\d+$/.test(trimmed)) return { value: parseFloat(trimmed) };
+
+  // Bare string (catch-all)
+  return { value: trimmed };
+}
+
+function splitFlowItems(inner) {
+  // Simple comma-split that respects quoted strings and nested brackets.
+  const items = [];
+  let depth = 0;
+  let inSingle = false;
+  let inDouble = false;
+  let current = '';
+
+  for (const ch of inner) {
+    if (inSingle) {
+      current += ch;
+      if (ch === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      current += ch;
+      if (ch === '"') inDouble = false;
+      continue;
+    }
+    if (ch === "'") { inSingle = true; current += ch; continue; }
+    if (ch === '"') { inDouble = true; current += ch; continue; }
+    if (ch === '[' || ch === '{') { depth++; current += ch; continue; }
+    if (ch === ']' || ch === '}') { depth--; current += ch; continue; }
+    if (ch === ',' && depth === 0) {
+      items.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += ch;
+  }
+  if (current.trim() !== '') items.push(current.trim());
+  return items;
+}
+
+module.exports = { parseFrontmatter };

package/pan-wizard-core/bin/lib/doc-lint/reporter.js

@@ -0,0 +1,45 @@
+'use strict';
+/**
+ * reporter.js — format violations for output.
+ *
+ * Two formats per DESIGN_SPEC.md §"CLI surface":
+ *   - human: <file>:<line> — <code> — <message>   (multi-line, colorless for v0.1)
+ *   - json:  NDJSON, one violation per line
+ */
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatHuman(violations) {
+  if (!violations || violations.length === 0) return '';
+  const lines = [];
+  for (const v of violations) {
+    const sev = v.severity === 'warning' ? '[warn]' : '[err] ';
+    lines.push(`${sev} ${v.file}:${v.line} — ${v.code} — ${v.message}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * @param {Array<Violation>} violations
+ * @returns {string}
+ */
+function formatJson(violations) {
+  if (!violations || violations.length === 0) return '';
+  return violations.map(v => JSON.stringify(v)).join('\n');
+}
+
+/**
+ * Returns a one-line summary suitable for end-of-run output.
+ * @param {Array<Violation>} violations
+ * @param {number} fileCount
+ * @returns {string}
+ */
+function summaryLine(violations, fileCount) {
+  const errors = violations.filter(v => v.severity === 'error').length;
+  const warnings = violations.filter(v => v.severity === 'warning').length;
+  return `Linted ${fileCount} file(s): ${errors} error(s), ${warnings} warning(s)`;
+}
+
+module.exports = { formatHuman, formatJson, summaryLine };