whale-igniter 1.5.2 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

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();

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
@@ -41,6 +42,9 @@ async function ensureIntelligenceFiles(target) {
 }
 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();

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";
@@ -17,8 +18,11 @@ import { ui } from "../ui/index.js";
  *   - 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/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

package/dist/index.js

@@ -39,25 +39,31 @@ program
     .description("Bootstrap a Whale workspace with AI-readable context (opinionated by default).")
     .option("-i, --interactive", "Run an interactive wizard to configure stack, packs, AI targets")
     .option("-m, --minimal", "Minimal scaffold: folders + config + one validator pack")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((projectName, opts) => igniteCommand(projectName, opts));
 program
     .command("init [projectName]")
     .description("Create an empty Whale workspace (no packs, no AI context).")
-    .action(async (projectName) => {
-    await initCommand(projectName);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action(async (projectName, opts) => {
+    await initCommand(projectName, opts);
 });
 program
     .command("sync [target]")
     .description("Regenerate CLAUDE.md and the LLM Wiki from project intelligence.")
-    .action(syncCommand);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => syncCommand(target, opts));
 program
     .command("remember [target]")
     .description("Update project memory for AI assistants (friendly alias for sync).")
-    .action((target) => rememberCommand(target));
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => rememberCommand(target, opts));
 program
     .command("check [target]")
     .description("Check project health and recommendations (validate + insights).")
-    .action((target) => checkCommand(target));
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .option("--full", "Show every validation issue instead of grouped summaries")
+    .action((target, opts) => checkCommand(target, opts));
 program
     .command("improve")
     .description("Ask Selene for project-wide improvement suggestions.")
@@ -73,7 +79,9 @@ program
 program
     .command("validate [target]")
     .description("Run operational validations (exits non-zero on errors).")
-    .action(validateCommand);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .option("--full", "Show every validation issue instead of grouped summaries")
+    .action((target, opts) => validateCommand(target, opts));
 program
     .command("docs [target]")
     .description("Generate validation report and run installed generator packs.")
@@ -81,7 +89,8 @@ program
 program
     .command("wiki [target]")
     .description("Regenerate AI context (alias of `sync`).")
-    .action(wikiCommand);
+    .option("--force", "Proceed even when the target does not look like a project directory")
+    .action((target, opts) => wikiCommand(target, opts));
 program
     .command("refine <note>")
     .description("Record an operational refinement. Mention an issue type to suppress matching issues.")
@@ -157,12 +166,14 @@ const insightsCmd = program
     .option("--category <name>", "Filter by category: refinements | decisions | components | foundations | tokens | coverage")
     .option("--min-severity <level>", "Show only insights at this severity or higher (info | warning | critical)")
     .option("--skip-scan", "Skip the source scan (faster, but disables orphan/drift insights)")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((target, opts) => insightsCommand(target, opts));
 insightsCmd
     .command("drift <category>")
     .description("Show or review drift in spacing | color | radii.")
     .option("--review", "Enter interactive review loop: accept as refinement, flag for refactor, or skip")
     .option("--target <path>", "Workspace path (default: cwd)")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((category, opts) => insightsDriftReviewCommand(category, opts));
 const create = program
     .command("create")
@@ -240,6 +251,7 @@ const adopt = program
     .description("Scan an existing project and propose components, foundations and decisions.")
     .option("--pattern <glob>", "Glob pattern for source files (default: src/**/*.{tsx,jsx})")
     .option("--dry-run", "Run the scanner but don't write proposals to disk")
+    .option("--force", "Proceed even when the target does not look like a project directory")
     .action((target, opts) => adoptCommand(target, opts));
 adopt
     .command("review [target]")

package/dist/templates/claude.js

@@ -33,7 +33,7 @@ export function renderRootIndex(config, stats) {
     const stack = config.stack ?? "css";
     const packs = (config.packs ?? []).join(", ") || "(none)";
     const refsSection = renderReferencesSection(config.uiReferences ?? []);
-    return `# AI Agent Context — ${name}
+    return `${stats.healthWarning ?? ""}# AI Agent Context — ${name}
 
 > This file is auto-generated by [Whale Igniter](https://github.com/whale-igniter).
 > Do not edit by hand. Run \`whale sync\` after changes to regenerate.
@@ -65,7 +65,15 @@ Whale stores structured context in two locations:
    - \`llm-wiki/COMPONENTS.md\` — component catalog
    - \`llm-wiki/WORKFLOWS.md\` — how the team uses Whale day to day
 
-**Current status:** ${stats.errors} error(s) · ${stats.warnings} warning(s) · ${stats.decisionCount} decision(s) · ${stats.refinementCount} refinement(s) · ${stats.componentCount} component(s)
+## Current status
+
+- Decisions: ${stats.decisionCount}
+- Active refinements: ${stats.refinementCount}
+- Components: ${stats.componentCount}
+
+### Validation
+
+${stats.validationSummary}
 
 ${refsSection}## How to work here
 

package/dist/templates/project.js

@@ -1,5 +1,5 @@
-export function renderProject(config, errors, warnings, refinementCount, decisionCount) {
-    return `# Project Context
+export function renderProject(config, validationSummary, healthWarning, refinementCount, decisionCount) {
+    return `${healthWarning ?? ""}# Project Context
 
 - **Project name:** ${config.projectName ?? "(unset)"}
 - **Project type:** ${config.projectType ?? "unspecified"}
@@ -10,11 +10,13 @@ export function renderProject(config, errors, warnings, refinementCount, decisio
 
 ## Current status
 
-- Validation errors: ${errors}
-- Validation warnings: ${warnings}
 - Decisions logged: ${decisionCount}
 - Active refinements: ${refinementCount}
 
+## Validation
+
+${validationSummary}
+
 _Generated by Whale Igniter._
 `;
 }

package/dist/utils/targetGuard.js

@@ -0,0 +1,77 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "fs-extra";
+import { ui } from "../ui/index.js";
+function isSamePath(a, b) {
+    return path.resolve(a) === path.resolve(b);
+}
+function isAncestorOf(ancestor, child) {
+    const relative = path.relative(ancestor, child);
+    return relative.length > 0 && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function projectMarkerMessage(target, command) {
+    const commandHint = command ? `whale ${command}` : "this command";
+    return [
+        `This does not look like a project directory: ${target}`,
+        "I could not find a .git directory or package.json there.",
+        `Run ${ui.code(commandHint)} from inside your project, pass an explicit project path, or add ${ui.code("--force")} if this really is the target you want.`
+    ].join("\n");
+}
+function protectedDirectoryMessage(target, command) {
+    const commandHint = command ? `whale ${command} path/to/project` : "pass an explicit project path";
+    return [
+        `I will not run in ${target}.`,
+        "That directory is your home folder, the filesystem root, or a parent of your home folder.",
+        `Please cd into a project directory first, or run ${ui.code(commandHint)}.`
+    ].join("\n");
+}
+export async function checkTargetDirectory(target, options = {}) {
+    const resolvedTarget = path.resolve(target);
+    const home = path.resolve(os.homedir());
+    const root = path.parse(resolvedTarget).root;
+    if (isSamePath(resolvedTarget, home) ||
+        isSamePath(resolvedTarget, root) ||
+        isAncestorOf(resolvedTarget, home)) {
+        return {
+            ok: false,
+            target: resolvedTarget,
+            reason: "protected-directory",
+            message: protectedDirectoryMessage(resolvedTarget, options.command)
+        };
+    }
+    const hasGit = await fs.pathExists(path.join(resolvedTarget, ".git"));
+    const hasPackageJson = await fs.pathExists(path.join(resolvedTarget, "package.json"));
+    if (!hasGit && !hasPackageJson) {
+        const message = projectMarkerMessage(resolvedTarget, options.command);
+        if (!options.force) {
+            return {
+                ok: false,
+                target: resolvedTarget,
+                reason: "missing-project-marker",
+                message
+            };
+        }
+        return {
+            ok: true,
+            target: resolvedTarget,
+            warning: message
+        };
+    }
+    return { ok: true, target: resolvedTarget };
+}
+export async function guardTargetDirectory(target, options = {}) {
+    const result = await checkTargetDirectory(target, options);
+    if (!result.ok) {
+        console.log();
+        console.log(ui.fail(result.message));
+        console.log();
+        process.exitCode = 1;
+        return false;
+    }
+    if (result.warning) {
+        console.log();
+        console.log(ui.warn(result.warning));
+        console.log();
+    }
+    return true;
+}

package/dist/utils/validationSummary.js

@@ -0,0 +1,103 @@
+export const VALIDATION_SUMMARY_LIMIT = 10;
+export const DEFAULT_HEALTH_ERROR_THRESHOLD = 500;
+export const DEFAULT_HEALTH_FILE_THRESHOLD = 1000;
+function groupKey(issue) {
+    return `${issue.severity}:${issue.type}`;
+}
+export function summarizeValidationIssues(issues, limit = VALIDATION_SUMMARY_LIMIT) {
+    const groupsByKey = new Map();
+    for (const issue of issues) {
+        const key = groupKey(issue);
+        const existing = groupsByKey.get(key);
+        if (existing) {
+            existing.count += 1;
+            existing.files.add(issue.file);
+            continue;
+        }
+        groupsByKey.set(key, {
+            key,
+            type: issue.type,
+            severity: issue.severity,
+            message: issue.message,
+            count: 1,
+            files: new Set([issue.file]),
+            example: issue
+        });
+    }
+    const groups = [...groupsByKey.values()].sort((a, b) => {
+        if (b.count !== a.count)
+            return b.count - a.count;
+        if (a.severity !== b.severity)
+            return a.severity === "error" ? -1 : 1;
+        return a.type.localeCompare(b.type);
+    });
+    const shownGroups = groups.slice(0, limit);
+    const hiddenGroups = groups.slice(limit);
+    const hiddenFiles = new Set();
+    let hiddenIssueCount = 0;
+    for (const group of hiddenGroups) {
+        hiddenIssueCount += group.count;
+        for (const file of group.files)
+            hiddenFiles.add(file);
+    }
+    return {
+        total: issues.length,
+        errors: issues.filter((issue) => issue.severity === "error").length,
+        warnings: issues.filter((issue) => issue.severity === "warning").length,
+        groups,
+        shownGroups,
+        hiddenIssueCount,
+        hiddenFileCount: hiddenFiles.size
+    };
+}
+export function evaluateValidationHealth(issues, scannedFileCount, config) {
+    const errorThreshold = config.validation?.healthErrorThreshold ?? DEFAULT_HEALTH_ERROR_THRESHOLD;
+    const fileThreshold = config.validation?.healthFileThreshold ?? DEFAULT_HEALTH_FILE_THRESHOLD;
+    const errorCount = issues.filter((issue) => issue.severity === "error").length;
+    const reasons = [];
+    if (errorCount > errorThreshold) {
+        reasons.push(`Validation errors exceed the configured threshold (${errorCount} > ${errorThreshold}).`);
+    }
+    if (scannedFileCount > fileThreshold) {
+        reasons.push(`The CSS scan touched ${scannedFileCount} files, which is above the configured threshold (${fileThreshold}).`);
+    }
+    return {
+        ok: reasons.length === 0,
+        errorThreshold,
+        fileThreshold,
+        reasons
+    };
+}
+export function formatIssueLocation(issue) {
+    return `${issue.file}:${issue.line}`;
+}
+export function renderValidationSummaryMarkdown(issues, options = {}) {
+    const summary = summarizeValidationIssues(issues, options.limit);
+    const fullCommand = options.fullCommand ?? "whale check --full";
+    if (summary.total === 0)
+        return "No validation issues found.";
+    const lines = ["Validation issues grouped by rule/cause.", ""];
+    for (const group of summary.shownGroups) {
+        const tag = group.severity.toUpperCase();
+        lines.push(`- **${group.type}** (${tag}) - ${group.count} issue(s); example \`${formatIssueLocation(group.example)}\` - ${group.message}`);
+    }
+    if (summary.hiddenIssueCount > 0) {
+        lines.push(`- + ${summary.hiddenIssueCount} more across ${summary.hiddenFileCount} files - run \`${fullCommand}\` for everything.`);
+    }
+    return lines.join("\n");
+}
+export function renderValidationHealthWarningMarkdown(verdict) {
+    if (verdict.ok)
+        return "";
+    return [
+        "# Whale Context Health Warning",
+        "",
+        "> This generated context is likely misconfigured and should not be trusted yet.",
+        "> Whale probably scanned the wrong directory, too broad a scope, or a project with missing ignores.",
+        "",
+        ...verdict.reasons.map((reason) => `- ${reason}`),
+        "",
+        "Run `whale check --full` from the intended project directory, or pass an explicit project path, then rerun `whale sync`.",
+        ""
+    ].join("\n");
+}

package/dist/validators/cssValidator.js

@@ -4,6 +4,13 @@ import path from "node:path";
 import postcss from "postcss";
 import { loadConfig } from "../utils/config.js";
 import { loadRefinements, isSuppressed } from "../utils/refinements.js";
+export async function findCssValidationFiles(target) {
+    return glob("**/*.css", {
+        cwd: target,
+        absolute: true,
+        ignore: ["node_modules/**", "dist/**", ".git/**"]
+    });
+}
 // Properties that take spacing values (length-based, grid-relevant).
 const SPACING_PROPS = new Set([
     "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
@@ -86,11 +93,7 @@ export async function validateCss(target, options = {}) {
         config.foundations?.radius?.control ?? 2,
         config.foundations?.radius?.container ?? 4
     ];
-    const files = await glob("**/*.css", {
-        cwd: target,
-        absolute: true,
-        ignore: ["node_modules/**", "dist/**", ".git/**"]
-    });
+    const files = await findCssValidationFiles(target);
     const issues = [];
     for (const file of files) {
         const content = await fs.readFile(file, "utf8");

package/dist/version.js

@@ -1 +1 @@
-export const PACKAGE_VERSION = "1.5.2";
+export const PACKAGE_VERSION = "1.5.3";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "CLI-first operational intelligence. Bootstraps and adopts AI-readable project context so agents like Claude Code, Codex and Cursor understand your design system from the first commit. Includes an MCP server, a file watcher, deterministic insights, and an opt-in AI bridge (Selene).",
   "type": "module",
   "main": "./dist/index.js",