whale-igniter 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to Whale Igniter are documented here.
 
+## 1.5.3 - 2026-07-06
+
+### Added
+
+- Added shared target-directory guardrails for commands that write files or scan projects, blocking home/root-level targets and requiring `--force` when no `.git` directory or `package.json` is present.
+- Added grouped validation summaries for CLI and generated docs, plus `--full` for exhaustive validation output and generated context health warnings when validation scope looks misconfigured.
+
+## 1.5.2 - 2026-06-10
+
+### Changed
+
+- Decisions and refinements are now stored as individual Markdown files with frontmatter (`intelligence/decisions/ADR-XXXX-*.md`, `intelligence/refinements/REF-XXXX-*.md`) instead of accumulative JSON stores. IDs are sequential and human-readable. `loadDecisions`/`loadRefinements` keep dual-reading legacy JSON, so existing projects lose no data.
+- `llm-wiki/DECISIONS.md` is now a compact index table linking to each decision's source file, instead of dumping full bodies — reducing the context an AI agent consumes.
+- Updated `glob` to its supported current major and refreshed the transitive MCP dependency tree; production audit reports zero vulnerabilities.
+
+### Security
+
+- `whale changes` now invokes git via `execFileSync` with argument arrays instead of shell-interpolated strings, removing a command-injection vector through the `--since` flag.
+
 ## 1.5.1 - 2026-06-03
 
 ### Added

package/README.md

@@ -34,12 +34,12 @@ my-app/
 ├── CLAUDE.md                  # agent-readable project brief, auto-synced
 ├── intelligence/
 │   ├── components.json        # component catalog with variants and states
-│   ├── decisions.json         # architectural decisions and their rationale
-│   └── refinements.json       # approved exceptions — "this is intentional"
+│   ├── decisions/             # one Markdown ADR per decision
+│   └── refinements/           # one Markdown file per approved exception
 └── llm-wiki/                  # generated markdown, one file per concern
 ```
 
-`intelligence/*.json` is the source of truth. Markdown is generated from it. When you run `whale sync`, everything regenerates — CLAUDE.md, the wiki, the context your agent reads on the next conversation.
+`whale.config.json` and `intelligence/` are the source of truth. Decisions and refinements use individual Markdown files with frontmatter; component metadata remains structured JSON. When you run `whale sync`, everything regenerates — CLAUDE.md, the wiki, and the context your agent reads on the next conversation.
 
 The agent doesn't guess anymore. It reads.
 

package/dist/commands/adopt.js

@@ -3,6 +3,7 @@ import fs from "fs-extra";
 import ora from "ora";
 import prompts from "prompts";
 import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { scanComponents } from "../scanner/componentScanner.js";
 import { aggregateTailwind, detectTailwindConfig } from "../scanner/tailwindScanner.js";
 import { inferFoundations } from "../scanner/foundationInferrer.js";
@@ -13,6 +14,9 @@ import { ui } from "../ui/index.js";
 const SCANNER_VERSION = "1.1.0";
 export async function adoptCommand(targetArg, options = {}) {
     const target = resolveTarget(targetArg);
+    if (!(await guardTargetDirectory(target, { force: options.force, command: "adopt" }))) {
+        return;
+    }
     console.log();
     console.log(ui.header("Whale Igniter", `adopt • ${path.relative(process.cwd(), target) || "."}`));
     console.log();
@@ -136,11 +140,13 @@ export async function adoptCommand(targetArg, options = {}) {
             console.log(ui.note("Updated stack to 'tailwind' in whale.config.json"));
         }
     }
-    // ---- Step 6: ensure other intelligence files exist ------------------------
-    for (const file of ["refinements.json", "decisions.json", "components.json"]) {
-        const p = path.join(target, "intelligence", file);
-        if (!(await fs.pathExists(p)))
-            await fs.writeJson(p, [], { spaces: 2 });
+    // ---- Step 6: ensure other intelligence stores exist -----------------------
+    const intelligenceDir = path.join(target, "intelligence");
+    await fs.ensureDir(path.join(intelligenceDir, "decisions"));
+    await fs.ensureDir(path.join(intelligenceDir, "refinements"));
+    const componentsPath = path.join(intelligenceDir, "components.json");
+    if (!(await fs.pathExists(componentsPath))) {
+        await fs.writeJson(componentsPath, [], { spaces: 2 });
     }
     // ---- Step 7: optional Selene enrichment -----------------------------------
     const ai = await getAiAvailability(target);

package/dist/commands/changes.js

@@ -1,21 +1,22 @@
-import { execSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import matter from "gray-matter";
 import { resolveTarget } from "../utils/paths.js";
-import { loadDecisions } from "../utils/decisions.js";
 import { loadComponents } from "../utils/components.js";
-import { loadRefinements } from "../utils/refinements.js";
 import { ui } from "../ui/index.js";
+const DECISIONS_DIR = "intelligence/decisions";
+const REFINEMENTS_DIR = "intelligence/refinements";
 const INTELLIGENCE_FILES = [
-    "intelligence/decisions.json",
+    DECISIONS_DIR,
+    REFINEMENTS_DIR,
     "intelligence/components.json",
-    "intelligence/refinements.json",
     "whale.config.json"
 ];
+function git(target, args) {
+    return execFileSync("git", args, { cwd: target, encoding: "utf8" });
+}
 function gitDiffFiles(target, since) {
     try {
-        const result = execSync(`git diff --name-only ${since} HEAD -- ${INTELLIGENCE_FILES.join(" ")}`, {
-            cwd: target,
-            encoding: "utf8"
-        });
+        const result = git(target, ["diff", "--name-only", since, "HEAD", "--", ...INTELLIGENCE_FILES]);
         return result.trim().split("\n").filter(Boolean);
     }
     catch {
@@ -24,13 +25,49 @@ function gitDiffFiles(target, since) {
 }
 function gitFileAtRef(target, ref, file) {
     try {
-        const raw = execSync(`git show ${ref}:${file}`, { cwd: target, encoding: "utf8" });
+        const raw = git(target, ["show", `${ref}:${file}`]);
         return JSON.parse(raw);
     }
     catch {
         return [];
     }
 }
+function mdLabelAtRef(target, ref, file, label) {
+    try {
+        const raw = git(target, ["show", `${ref}:${file}`]);
+        return label(raw) || file;
+    }
+    catch {
+        return file;
+    }
+}
+const decisionLabel = (raw) => {
+    const title = matter(raw).data?.title;
+    return title ? String(title) : "";
+};
+const refinementLabel = (raw) => matter(raw).content.trim().split("\n")[0] ?? "";
+function gitDirChanges(target, since, dir, label) {
+    const result = { added: [], removed: [], modified: [] };
+    let raw = "";
+    try {
+        raw = git(target, ["diff", "--name-status", since, "HEAD", "--", dir]);
+    }
+    catch {
+        return result;
+    }
+    for (const line of raw.trim().split("\n").filter(Boolean)) {
+        const [status, file] = line.split("\t");
+        if (!file || !file.endsWith(".md"))
+            continue;
+        if (status.startsWith("A"))
+            result.added.push(mdLabelAtRef(target, "HEAD", file, label));
+        else if (status.startsWith("D"))
+            result.removed.push(mdLabelAtRef(target, since, file, label));
+        else if (status.startsWith("M") || status.startsWith("R"))
+            result.modified.push(mdLabelAtRef(target, "HEAD", file, label));
+    }
+    return result;
+}
 export async function changesCommand(opts) {
     const target = resolveTarget(opts.target);
     const since = opts.since ?? "HEAD~1";
@@ -49,21 +86,8 @@ export async function changesCommand(opts) {
     if (changedFiles.includes("whale.config.json")) {
         summary.configChanged = true;
     }
-    if (changedFiles.includes("intelligence/decisions.json")) {
-        const before = gitFileAtRef(target, since, "intelligence/decisions.json");
-        const after = await loadDecisions(target);
-        const beforeIds = new Map(before.map((d) => [d.id, d.title]));
-        const afterIds = new Map(after.map((d) => [d.id, d.title]));
-        for (const [id, title] of afterIds) {
-            if (!beforeIds.has(id))
-                summary.decisions.added.push(title);
-        }
-        for (const [id, title] of beforeIds) {
-            if (!afterIds.has(id))
-                summary.decisions.removed.push(title);
-            else if (afterIds.get(id) !== title)
-                summary.decisions.modified.push(title);
-        }
+    if (changedFiles.some((f) => f.startsWith(`${DECISIONS_DIR}/`))) {
+        summary.decisions = gitDirChanges(target, since, DECISIONS_DIR, decisionLabel);
     }
     if (changedFiles.includes("intelligence/components.json")) {
         const before = gitFileAtRef(target, since, "intelligence/components.json");
@@ -79,20 +103,10 @@ export async function changesCommand(opts) {
                 summary.components.removed.push(name);
         }
     }
-    if (changedFiles.includes("intelligence/refinements.json")) {
-        const before = gitFileAtRef(target, since, "intelligence/refinements.json");
-        const after = await loadRefinements(target);
-        const beforeIds = new Set(before.map((r) => r.id));
-        const afterIds = new Set(after.map((r) => r.id));
-        const beforeNotes = new Map(before.map((r) => [r.id, r.note]));
-        for (const r of after) {
-            if (!beforeIds.has(r.id))
-                summary.refinements.added.push(r.note);
-        }
-        for (const [id, note] of beforeNotes) {
-            if (!afterIds.has(id))
-                summary.refinements.removed.push(note);
-        }
+    if (changedFiles.some((f) => f.startsWith(`${REFINEMENTS_DIR}/`))) {
+        const changes = gitDirChanges(target, since, REFINEMENTS_DIR, refinementLabel);
+        summary.refinements.added = changes.added;
+        summary.refinements.removed = changes.removed;
     }
     // ---- Render ----------------------------------------------------------------
     if (summary.configChanged) {

package/dist/commands/decision.js

@@ -86,7 +86,7 @@ export async function decisionCommand(options = {}) {
         consequences: consequences?.trim() || undefined
     });
     console.log();
-    console.log(ui.ok(`Decision recorded ${ui.muted("— " + created.id.slice(0, 8))}`));
+    console.log(ui.ok(`Decision recorded ${ui.muted("— " + created.id)}`));
     console.log(`  ${ui.accent(created.title)}`);
     console.log(`  ${ui.kv("category", created.category, { keyWidth: 8 })}`);
     if (options.sync !== false) {

package/dist/commands/friendly.js

@@ -5,20 +5,26 @@ import { syncCommand } from "./sync.js";
 import { validateCommand } from "./validate.js";
 import { wikiCommand } from "./wiki.js";
 import { ui } from "../ui/index.js";
-export async function rememberCommand(target) {
+import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
+export async function rememberCommand(target, options = {}) {
     console.log();
     console.log(ui.header("Whale Igniter", "remember"));
     console.log(ui.muted("Updating project memory for AI assistants."));
-    await syncCommand(target);
+    await syncCommand(target, options);
 }
-export async function checkCommand(target) {
+export async function checkCommand(target, options = {}) {
     console.log();
     console.log(ui.header("Whale Igniter", "check"));
     console.log(ui.muted("Checking project health, then looking for useful recommendations."));
     console.log();
-    await validateCommand(target);
+    const resolvedTarget = resolveTarget(target);
+    if (!(await guardTargetDirectory(resolvedTarget, { force: options.force, command: "check" }))) {
+        return;
+    }
+    await validateCommand(target, { ...options, skipTargetGuard: true });
     const validationExit = process.exitCode;
-    await insightsCommand(target, {});
+    await insightsCommand(target, { ...options, skipTargetGuard: true });
     if (validationExit !== undefined) {
         process.exitCode = validationExit;
     }

package/dist/commands/ignite.js

@@ -7,6 +7,7 @@ import { validateCss } from "../validators/cssValidator.js";
 import { generateWiki } from "../generators/wikiGenerator.js";
 import { appendDecision } from "../utils/decisions.js";
 import { getAiAvailability } from "../utils/aiAvailability.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { mapWizardAnswers, suggestUiCategories } from "../utils/wizardMapping.js";
 import { ui } from "../ui/index.js";
 import { PACKAGE_VERSION } from "../version.js";
@@ -49,7 +50,11 @@ export async function igniteCommand(projectName = "whale-project", options = {})
     }
     // ---- Step 1: scaffold workspace -------------------------------------------
     const resolvedProjectName = config.projectName ?? projectName;
-    const target = await initCommand(resolvedProjectName, { config, silent: true });
+    const plannedTarget = path.resolve(process.cwd(), resolvedProjectName);
+    if (!(await guardTargetDirectory(plannedTarget, { force: options.force, command: "ignite" }))) {
+        return;
+    }
+    const target = await initCommand(resolvedProjectName, { config, silent: true, skipTargetGuard: true });
     const targetRel = path.relative(process.cwd(), target) || ".";
     console.log(ui.ok(`Workspace created at ${ui.path(targetRel)}`));
     // ---- Step 1b: record free-text project intent as first decision ------------

package/dist/commands/init.js

@@ -2,6 +2,7 @@ import path from "node:path";
 import fs from "fs-extra";
 import ora from "ora";
 import { DEFAULT_CONFIG, saveConfig } from "../utils/config.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { ui } from "../ui/index.js";
 /**
  * Folders Whale always expects to exist. Created empty so subsequent
@@ -27,8 +28,6 @@ async function ensureIntelligenceFiles(target) {
     const intelligenceDir = path.join(target, "intelligence");
     await fs.ensureDir(intelligenceDir);
     const seeds = {
-        "refinements.json": [],
-        "decisions.json": [],
         "components.json": []
     };
     for (const [name, content] of Object.entries(seeds)) {
@@ -37,9 +36,15 @@ async function ensureIntelligenceFiles(target) {
             await fs.writeJson(file, content, { spaces: 2 });
         }
     }
+    // Decisions and refinements are stored as individual Markdown files.
+    await fs.ensureDir(path.join(intelligenceDir, "decisions"));
+    await fs.ensureDir(path.join(intelligenceDir, "refinements"));
 }
 export async function initCommand(projectName = "whale-project", options = {}) {
     const target = path.resolve(process.cwd(), projectName);
+    if (!options.skipTargetGuard && !(await guardTargetDirectory(target, { force: options.force, command: "init" }))) {
+        return target;
+    }
     const spinner = options.silent
         ? null
         : ora(`Scaffolding ${projectName}`).start();

package/dist/commands/insights.js

@@ -3,6 +3,7 @@ import fs from "fs-extra";
 import ora from "ora";
 import prompts from "prompts";
 import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { loadConfig } from "../utils/config.js";
 import { loadRefinements, appendRefinement } from "../utils/refinements.js";
 import { loadDecisions } from "../utils/decisions.js";
@@ -21,6 +22,9 @@ import { randomUUID } from "node:crypto";
 const SEVERITY_RANK = { info: 0, warning: 1, critical: 2 };
 export async function insightsCommand(targetArg, options = {}) {
     const target = resolveTarget(targetArg);
+    if (!options.skipTargetGuard && !(await guardTargetDirectory(target, { force: options.force, command: "insights" }))) {
+        return;
+    }
     if (!(await fs.pathExists(path.join(target, "whale.config.json")))) {
         console.log();
         console.log(ui.warn("No whale.config.json found at this target. Run `whale ignite` or `whale adopt` first."));
@@ -99,6 +103,9 @@ export async function insightsDriftReviewCommand(category, opts) {
     }
     const cat = category;
     const target = resolveTarget(opts.target);
+    if (!(await guardTargetDirectory(target, { force: opts.force, command: "insights drift" }))) {
+        return;
+    }
     console.log();
     console.log(ui.header("Whale Igniter", `insights drift ${cat}`));
     console.log();
@@ -168,8 +175,6 @@ export async function insightsDriftReviewCommand(category, opts) {
             break;
         if (action === "refine") {
             await appendRefinement(target, {
-                id: randomUUID(),
-                timestamp: new Date().toISOString(),
                 note: ins.title,
                 scope: { issueType: cat }
             });

package/dist/commands/refine.js

@@ -1,4 +1,3 @@
-import { randomUUID } from "node:crypto";
 import { resolveTarget } from "../utils/paths.js";
 import { appendRefinement, inferScope } from "../utils/refinements.js";
 import { generateWiki } from "../generators/wikiGenerator.js";
@@ -6,13 +5,7 @@ import { ui } from "../ui/index.js";
 export async function refineCommand(note, options = {}) {
     const target = resolveTarget();
     const scope = inferScope(note);
-    const refinement = {
-        id: randomUUID(),
-        timestamp: new Date().toISOString(),
-        note,
-        scope
-    };
-    await appendRefinement(target, refinement);
+    await appendRefinement(target, { note, scope });
     console.log(ui.ok("Refinement recorded"));
     if (scope) {
         const parts = [];

package/dist/commands/selene.js

@@ -14,7 +14,6 @@ import { copyToClipboard } from "../selene/clipboard.js";
 import { resolveProvider, describeProviderState } from "../selene/providers.js";
 import { callProvider, estimateTokens, estimateCostUsd } from "../selene/apiClient.js";
 import { readCache, writeCache, clearCache } from "../selene/cache.js";
-import { randomUUID } from "node:crypto";
 import { ui } from "../ui/index.js";
 const PENDING_DIR = ".whale/selene";
 // ---------------------------------------------------------------------------
@@ -421,8 +420,6 @@ async function applySuggest(target, raw, options) {
             }
             else if (s.kind === "refinement") {
                 await appendRefinement(target, {
-                    id: randomUUID(),
-                    timestamp: new Date().toISOString(),
                     note: s.proposed_text
                 });
                 console.log(ui.success("  ✓ Recorded as refinement."));

package/dist/commands/sync.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import ora from "ora";
 import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { generateWiki } from "../generators/wikiGenerator.js";
 import { loadConfig } from "../utils/config.js";
 import { loadDecisions } from "../utils/decisions.js";
@@ -10,15 +11,18 @@ import { getAiAvailability } from "../utils/aiAvailability.js";
 import { ui } from "../ui/index.js";
 /**
  * `whale sync` regenerates everything an AI agent reads, from the
- * intelligence JSON files (which are the source of truth).
+ * project configuration and intelligence stores (the source of truth).
  *
  * Run this:
- *   - after manually editing intelligence/*.json
+ *   - after manually editing whale.config.json or intelligence stores
  *   - before handing the project to an AI agent
  *   - in CI to ensure CLAUDE.md stays in sync
  */
-export async function syncCommand(targetArg) {
+export async function syncCommand(targetArg, options = {}) {
     const target = resolveTarget(targetArg);
+    if (!(await guardTargetDirectory(target, { force: options.force, command: "sync" }))) {
+        return;
+    }
     const spinner = ora("Reading intelligence stores").start();
     const config = await loadConfig(target);
     const decisions = await loadDecisions(target);

package/dist/commands/validate.js

@@ -1,9 +1,14 @@
 import ora from "ora";
 import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { validateCss, hasErrors } from "../validators/cssValidator.js";
+import { formatIssueLocation, summarizeValidationIssues } from "../utils/validationSummary.js";
 import { ui } from "../ui/index.js";
-export async function validateCommand(targetArg) {
+export async function validateCommand(targetArg, options = {}) {
     const target = resolveTarget(targetArg);
+    if (!options.skipTargetGuard && !(await guardTargetDirectory(target, { force: options.force, command: "validate" }))) {
+        return;
+    }
     const spinner = ora("Scanning workspace").start();
     let issues;
     try {
@@ -23,7 +28,33 @@ export async function validateCommand(targetArg) {
         process.exitCode = 0;
         return;
     }
-    // Header with the counts as badges.
+    if (!options.full) {
+        const summary = summarizeValidationIssues(issues);
+        console.log();
+        console.log(ui.section("Top issue groups"));
+        console.log();
+        for (const group of summary.shownGroups) {
+            const head = group.severity === "error"
+                ? `${ui.glyph.cross} ${ui.danger(group.type)}`
+                : `${ui.glyph.warn} ${ui.warning(group.type)}`;
+            console.log(`${head} ${ui.muted(`- ${group.count} issue(s)`)}`);
+            console.log(`  example: ${ui.path(formatIssueLocation(group.example))}`);
+            console.log(`  ${group.message}`);
+            console.log(`  ${ui.next(group.example.suggestion)}`);
+            if (group.example.selector) {
+                console.log(`  ${ui.muted("selector: " + group.example.selector)}`);
+            }
+            console.log();
+        }
+        if (summary.hiddenIssueCount > 0) {
+            console.log(ui.muted(`+ ${summary.hiddenIssueCount} more across ${summary.hiddenFileCount} files - run \`whale check --full\` for everything`));
+            console.log();
+        }
+        process.exitCode = hasErrors(issues) ? 1 : 0;
+        return;
+    }
+    // Header with the counts as badges. Kept for --full, which preserves the
+    // older exhaustive output for users who explicitly ask for everything.
     console.log();
     console.log(ui.summary([
         { label: "issues", value: issues.length },

package/dist/commands/watch.js

@@ -3,7 +3,7 @@
  *
  * Why this exists. Whale's value depends on CLAUDE.md being current.
  * Every write command (refine, decision, component add, adopt review) auto-syncs,
- * but humans also edit `intelligence/*.json` directly, change `whale.config.json`,
+ * but humans also edit `intelligence/` directly, change `whale.config.json`,
  * or commit catalog files from another tool. Without a watcher the gap between
  * "what's true" and "what the AI sees" silently widens. Watcher closes that gap.
  *

package/dist/commands/wiki.js

@@ -1,10 +1,14 @@
 import path from "node:path";
 import ora from "ora";
 import { resolveTarget } from "../utils/paths.js";
+import { guardTargetDirectory } from "../utils/targetGuard.js";
 import { generateWiki } from "../generators/wikiGenerator.js";
 import { ui } from "../ui/index.js";
-export async function wikiCommand(targetArg) {
+export async function wikiCommand(targetArg, options = {}) {
     const target = resolveTarget(targetArg);
+    if (!(await guardTargetDirectory(target, { force: options.force, command: "wiki" }))) {
+        return;
+    }
     const spinner = ora("Generating AI context").start();
     const { rootFiles, wikiFiles } = await generateWiki(target);
     spinner.succeed("AI context generated");

package/dist/generators/markdownGenerator.js

@@ -3,6 +3,7 @@ import fs from "fs-extra";
 import { loadConfig } from "../utils/config.js";
 import { loadRefinements } from "../utils/refinements.js";
 import { validateCss } from "../validators/cssValidator.js";
+import { renderValidationSummaryMarkdown, summarizeValidationIssues } from "../utils/validationSummary.js";
 async function buildContext(target) {
     const config = await loadConfig(target);
     const refinements = await loadRefinements(target);
@@ -27,11 +28,20 @@ function renderForge(ctx) {
         "- All interactive elements MUST have a `:focus-visible` style.",
         "- Color values MUST come from semantic tokens (`var(--color-*)`).",
         "",
-        `## Open Issues (${issues.length})`,
+        "## Open Issues",
         ""
     ];
-    for (const issue of issues) {
-        lines.push(`- \`${issue.file}:${issue.line}\` — ${issue.type}: ${issue.message}`);
+    if (issues.length === 0) {
+        lines.push("No validation issues found.");
+    }
+    else {
+        const summary = summarizeValidationIssues(issues);
+        for (const group of summary.shownGroups) {
+            lines.push(`- **${group.type}** (${group.severity.toUpperCase()}) - ${group.count} issue(s); example \`${group.example.file}:${group.example.line}\` - ${group.message}`);
+        }
+        if (summary.hiddenIssueCount > 0) {
+            lines.push(`- + ${summary.hiddenIssueCount} more across ${summary.hiddenFileCount} files - run \`whale check --full\` for everything.`);
+        }
     }
     return lines.join("\n") + "\n";
 }
@@ -59,13 +69,11 @@ function renderScribe(ctx) {
     lines.push("");
     lines.push(`## Current Validation Status`);
     lines.push("");
-    lines.push(`${issues.length} issue(s) open. Run \`whale validate\` for details.`);
+    lines.push(renderValidationSummaryMarkdown(issues));
     return lines.join("\n") + "\n";
 }
 function renderAtlas(ctx) {
     const { config, refinements, issues } = ctx;
-    const errors = issues.filter((i) => i.severity === "error").length;
-    const warnings = issues.filter((i) => i.severity === "warning").length;
     const lines = [
         "# Atlas — Product Strategy",
         "",
@@ -77,10 +85,10 @@ function renderAtlas(ctx) {
         `- Accent: ${config.branding?.accent ?? "unspecified"}`,
         "",
         "## Operational Health",
-        `- Errors: ${errors}`,
-        `- Warnings: ${warnings}`,
         `- Decisions logged: ${refinements.length}`,
         "",
+        renderValidationSummaryMarkdown(issues),
+        "",
         "## Decision Log",
         ""
     ];

package/dist/generators/reportGenerator.js

@@ -1,11 +1,10 @@
 import path from "node:path";
 import fs from "fs-extra";
 import { validateCss } from "../validators/cssValidator.js";
+import { renderValidationSummaryMarkdown } from "../utils/validationSummary.js";
 export async function generateValidationReport(target) {
     const issues = await validateCss(target);
     const reportPath = path.join(target, "docs", "validation-report.md");
-    const errors = issues.filter((i) => i.severity === "error");
-    const warnings = issues.filter((i) => i.severity === "warning");
     const lines = [
         "# Whale Validation Report",
         "",
@@ -13,37 +12,12 @@ export async function generateValidationReport(target) {
         "",
         "## Summary",
         "",
-        `- Total issues: **${issues.length}**`,
-        `- Errors: **${errors.length}**`,
-        `- Warnings: **${warnings.length}**`,
+        renderValidationSummaryMarkdown(issues),
         ""
     ];
     if (issues.length === 0) {
         lines.push("✓ Clean run.");
     }
-    else {
-        // Group by file so the report is actionable.
-        const byFile = new Map();
-        for (const issue of issues) {
-            const arr = byFile.get(issue.file) ?? [];
-            arr.push(issue);
-            byFile.set(issue.file, arr);
-        }
-        for (const [file, fileIssues] of byFile) {
-            lines.push(`## ${file}`);
-            lines.push("");
-            for (const issue of fileIssues) {
-                const tag = issue.severity === "error" ? "ERROR" : "WARNING";
-                lines.push(`- **${tag}** (${issue.type}) at line ${issue.line}`);
-                lines.push(`  - ${issue.message}`);
-                lines.push(`  - Fix: ${issue.suggestion}`);
-                if (issue.selector) {
-                    lines.push(`  - Selector: \`${issue.selector}\``);
-                }
-            }
-            lines.push("");
-        }
-    }
     await fs.ensureDir(path.dirname(reportPath));
     await fs.writeFile(reportPath, lines.join("\n"));
     return reportPath;

package/dist/generators/wikiGenerator.js

@@ -4,7 +4,8 @@ import { loadConfig } from "../utils/config.js";
 import { loadRefinements } from "../utils/refinements.js";
 import { loadDecisions } from "../utils/decisions.js";
 import { loadComponents } from "../utils/components.js";
-import { validateCss } from "../validators/cssValidator.js";
+import { findCssValidationFiles, validateCss } from "../validators/cssValidator.js";
+import { evaluateValidationHealth, renderValidationHealthWarningMarkdown, renderValidationSummaryMarkdown } from "../utils/validationSummary.js";
 import { renderFoundations } from "../templates/foundations.js";
 import { renderConventions } from "../templates/conventions.js";
 import { renderDecisions } from "../templates/decisions.js";
@@ -16,14 +17,19 @@ export async function generateWiki(target) {
     const refinements = await loadRefinements(target);
     const decisions = await loadDecisions(target);
     const components = await loadComponents(target);
-    const issues = await validateCss(target);
+    const [issues, scannedFiles] = await Promise.all([
+        validateCss(target),
+        findCssValidationFiles(target)
+    ]);
     const errors = issues.filter((i) => i.severity === "error").length;
     const warnings = issues.filter((i) => i.severity === "warning").length;
+    const validationSummary = renderValidationSummaryMarkdown(issues);
+    const healthWarning = renderValidationHealthWarningMarkdown(evaluateValidationHealth(issues, scannedFiles.length, config));
     const wikiDir = path.join(target, "llm-wiki");
     await fs.ensureDir(wikiDir);
     const themedFiles = {
         "README.md": renderWikiReadme(config),
-        "PROJECT.md": renderProject(config, errors, warnings, refinements.length, decisions.length),
+        "PROJECT.md": renderProject(config, validationSummary, healthWarning, refinements.length, decisions.length),
         "FOUNDATIONS.md": renderFoundations(config, decisions),
         "CONVENTIONS.md": renderConventions(config, refinements),
         "DECISIONS.md": renderDecisions(decisions),
@@ -39,6 +45,8 @@ export async function generateWiki(target) {
     const rootIndex = renderRootIndex(config, {
         errors,
         warnings,
+        validationSummary,
+        healthWarning,
         refinementCount: refinements.length,
         decisionCount: decisions.length,
         componentCount: components.length