whale-igniter 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to Whale Igniter are documented here.
 
+## 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

@@ -136,11 +136,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/init.js

@@ -27,8 +27,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,6 +35,9 @@ 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);

package/dist/commands/insights.js

@@ -168,8 +168,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

@@ -10,10 +10,10 @@ 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
  */

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/index.js

@@ -48,7 +48,7 @@ program
 });
 program
     .command("sync [target]")
-    .description("Regenerate CLAUDE.md and the LLM Wiki from intelligence/*.json.")
+    .description("Regenerate CLAUDE.md and the LLM Wiki from project intelligence.")
     .action(syncCommand);
 program
     .command("remember [target]")

package/dist/mcp/server.js

@@ -38,7 +38,6 @@ import { collectReferencedFiles, normalizePath } from "../analyzer/imports.js";
 import { scanComponents } from "../scanner/componentScanner.js";
 import { aggregateTailwind } from "../scanner/tailwindScanner.js";
 import { validateCss } from "../validators/cssValidator.js";
-import { randomUUID } from "node:crypto";
 import { PACKAGE_VERSION } from "../version.js";
 function ok(text) {
     return { content: [{ type: "text", text }] };
@@ -354,12 +353,7 @@ export function buildMcpServer() {
         if (!check.ok)
             return err(check.reason);
         const scope = inferScope(note);
-        await appendRefinement(ws, {
-            id: randomUUID(),
-            timestamp: new Date().toISOString(),
-            note,
-            scope
-        });
+        await appendRefinement(ws, { note, scope });
         await generateWiki(ws);
         const scopeDesc = scope
             ? `Scope inferred: ${Object.entries(scope).map(([k, v]) => `${k}=${v}`).join(", ")}.`
@@ -368,8 +362,8 @@ export function buildMcpServer() {
     });
     server.registerTool("whale_sync", {
         title: "Regenerate CLAUDE.md and the LLM wiki",
-        description: "Regenerates the AI-readable context files from intelligence/*.json. Call " +
-            "this if you've manually edited the JSON stores and want the wiki to catch " +
+        description: "Regenerates the AI-readable context files from project intelligence. Call " +
+            "this if you've manually edited the source stores and want the wiki to catch " +
             "up. Whale auto-syncs on every recorded change, so manual calls are rarely needed.",
         inputSchema: { target: z.string().optional() }
     }, async ({ target }) => {

package/dist/selene/promptBuilder.js

@@ -42,7 +42,7 @@ function renderProjectContext(ctx) {
     lines.push(`- Control radius: ${c.foundations?.radius?.control ?? 4}px (buttons, inputs)`);
     lines.push(`- Container radius: ${c.foundations?.radius?.container ?? 8}px (cards, modals)`);
     // Active decisions — show titles only to keep tokens down. Full text
-    // is available in intelligence/decisions.json if the model needs it.
+    // is available in the linked intelligence/decisions Markdown files.
     const active = ctx.decisions.filter((d) => d.status === "active");
     if (active.length > 0) {
         lines.push("");
@@ -52,7 +52,7 @@ function renderProjectContext(ctx) {
             lines.push(`- [${d.category}] ${d.title}`);
         }
         if (active.length > recent.length) {
-            lines.push(`- … and ${active.length - recent.length} more in intelligence/decisions.json`);
+            lines.push(`- … and ${active.length - recent.length} more in llm-wiki/DECISIONS.md`);
         }
     }
     if (ctx.refinements.length > 0) {

package/dist/templates/claude.js

@@ -53,12 +53,12 @@ the design system, conventions and decisions without re-explaining them every se
 
 Whale stores structured context in two locations:
 
-1. **\`intelligence/\`** — source of truth (JSON). Prefer these for precise data:
-   - \`intelligence/refinements.json\` — approved validator overrides
-   - \`intelligence/decisions.json\` — architectural and product decisions
+1. **\`intelligence/\`** — source of truth. Prefer these for precise data:
+   - \`intelligence/refinements/\` — approved validator overrides as Markdown
+   - \`intelligence/decisions/\` — architectural and product decisions as ADRs
    - \`intelligence/components.json\` — component catalog
 
-2. **\`llm-wiki/\`** — human + AI readable markdown rendered from the JSON:
+2. **\`llm-wiki/\`** — compact human + AI readable markdown indexes:
    - \`llm-wiki/FOUNDATIONS.md\` — design tokens and grid rules
    - \`llm-wiki/CONVENTIONS.md\` — coding and design conventions
    - \`llm-wiki/DECISIONS.md\` — decision log in narrative form

package/dist/templates/conventions.js

@@ -28,7 +28,8 @@ export function renderConventions(config, refinements) {
             if (r.scope?.file)
                 scopeParts.push(`file=\`${r.scope.file}\``);
             const scope = scopeParts.length ? ` _(${scopeParts.join(", ")})_` : "";
-            lines.push(`- **${r.timestamp.slice(0, 10)}** — ${r.note}${scope}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`- **${ref}** · ${r.timestamp.slice(0, 10)} — ${r.note}${scope}`);
         }
         lines.push("");
     }
@@ -36,7 +37,8 @@ export function renderConventions(config, refinements) {
         lines.push("## Open questions", "");
         lines.push("These notes do not yet have a scope — the validator cannot act on them.", "Review and convert to scoped refinements or decisions.", "");
         for (const r of scopeless) {
-            lines.push(`> ⚠️ Unresolved — **${r.timestamp.slice(0, 10)}**: ${r.note}`);
+            const ref = r.sourcePath ? `[${r.id}](../${r.sourcePath})` : r.id;
+            lines.push(`> ⚠️ Unresolved — **${ref}** · ${r.timestamp.slice(0, 10)}: ${r.note}`);
         }
         lines.push("");
     }

package/dist/templates/decisions.js

@@ -1,12 +1,21 @@
-const MAX_DETAIL = 500;
-function truncate(text) {
-    return text.length > MAX_DETAIL ? text.slice(0, MAX_DETAIL) + "…" : text;
+const MAX_SUMMARY = 120;
+function summarize(d) {
+    const text = (d.context ?? d.decision).replace(/\s+/g, " ").trim();
+    const oneLine = text.length > MAX_SUMMARY ? text.slice(0, MAX_SUMMARY) + "…" : text;
+    return oneLine.replace(/\|/g, "\\|");
+}
+function linkFor(d) {
+    // Wiki lives in llm-wiki/; decisions live in intelligence/decisions/.
+    if (!d.sourcePath)
+        return d.title;
+    return `[${d.title}](../${d.sourcePath})`;
 }
 export function renderDecisions(decisions) {
     const lines = [
         "# Decision Log",
         "",
-        "Architectural, product and tooling decisions, most recent first.",
+        "Compact index of architectural, product and tooling decisions, most recent first.",
+        "Open the linked file for full Context / Decision / Consequences.",
         ""
     ];
     if (decisions.length === 0) {
@@ -14,20 +23,12 @@ export function renderDecisions(decisions) {
     }
     else {
         const sorted = [...decisions].sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        lines.push("| ID | Decision | Category | Status | Summary |");
+        lines.push("| --- | --- | --- | --- | --- |");
         for (const d of sorted) {
-            lines.push(`## ${d.title}`);
-            lines.push("");
-            lines.push(`_${d.timestamp.slice(0, 10)} · ${d.category} · ${d.status}_`);
-            lines.push("");
-            if (d.context) {
-                lines.push("**Context**", "", truncate(d.context), "");
-            }
-            lines.push("**Decision**", "", truncate(d.decision));
-            if (d.consequences) {
-                lines.push("", "**Consequences**", "", truncate(d.consequences));
-            }
-            lines.push("", "---", "");
+            lines.push(`| ${d.id} | ${linkFor(d)} | ${d.category} | ${d.status} | ${summarize(d)} |`);
         }
+        lines.push("");
     }
     lines.push("_Generated by Whale Igniter._");
     return lines.join("\n");

package/dist/utils/decisions.js

@@ -1,9 +1,60 @@
 import path from "node:path";
 import fs from "fs-extra";
-import { randomUUID } from "node:crypto";
-const STORE = "intelligence/decisions.json";
-export async function loadDecisions(target) {
-    const file = path.join(target, STORE);
+import matter from "gray-matter";
+const DIR = "intelligence/decisions";
+const LEGACY_STORE = "intelligence/decisions.json";
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function section(body, heading) {
+    const re = new RegExp(`^##\\s+${heading}\\s*$([\\s\\S]*?)(?=^##\\s+|(?![\\s\\S]))`, "im");
+    const match = body.match(re);
+    const text = match?.[1]?.trim();
+    return text && text.length > 0 ? text : undefined;
+}
+function parseFile(raw) {
+    const { data, content } = matter(raw);
+    const decision = section(content, "Decision");
+    if (!data.id || !data.title || !decision)
+        return null;
+    return {
+        id: String(data.id),
+        timestamp: String(data.createdAt ?? data.timestamp ?? ""),
+        title: String(data.title),
+        category: (data.category ?? "architecture"),
+        context: section(content, "Context"),
+        decision,
+        consequences: section(content, "Consequences"),
+        status: (data.status ?? "active"),
+        supersedes: data.supersedes ? String(data.supersedes) : undefined
+    };
+}
+function serialize(d) {
+    const fm = matter.stringify([
+        "## Context",
+        d.context ?? "",
+        "",
+        "## Decision",
+        d.decision,
+        "",
+        "## Consequences",
+        d.consequences ?? ""
+    ].join("\n"), {
+        id: d.id,
+        title: d.title,
+        category: d.category,
+        status: d.status,
+        createdAt: d.timestamp,
+        supersedes: d.supersedes ?? null
+    });
+    return fm;
+}
+async function loadLegacy(target) {
+    const file = path.join(target, LEGACY_STORE);
     if (!(await fs.pathExists(file)))
         return [];
     try {
@@ -13,20 +64,49 @@ export async function loadDecisions(target) {
         return [];
     }
 }
-export async function saveDecisions(target, decisions) {
-    const file = path.join(target, STORE);
-    await fs.ensureDir(path.dirname(file));
-    await fs.writeJson(file, decisions, { spaces: 2 });
+export async function loadDecisions(target) {
+    const dir = path.join(target, DIR);
+    const fromFiles = [];
+    if (await fs.pathExists(dir)) {
+        const entries = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+        for (const entry of entries) {
+            const raw = await fs.readFile(path.join(dir, entry), "utf8");
+            const parsed = parseFile(raw);
+            if (parsed) {
+                parsed.sourcePath = `${DIR}/${entry}`;
+                fromFiles.push(parsed);
+            }
+        }
+    }
+    // Dual read: surface legacy JSON entries that haven't been migrated yet.
+    const legacy = await loadLegacy(target);
+    const seen = new Set(fromFiles.map((d) => d.id));
+    for (const d of legacy) {
+        if (!seen.has(d.id))
+            fromFiles.push(d);
+    }
+    return fromFiles;
+}
+function nextId(existing) {
+    let max = 0;
+    for (const d of existing) {
+        const m = /^ADR-(\d+)$/.exec(d.id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `ADR-${String(max + 1).padStart(4, "0")}`;
 }
 export async function appendDecision(target, input) {
-    const decisions = await loadDecisions(target);
+    const existing = await loadDecisions(target);
     const decision = {
-        id: randomUUID(),
-        timestamp: new Date().toISOString(),
+        id: nextId(existing),
+        timestamp: new Date().toISOString().slice(0, 10),
         status: "active",
         ...input
     };
-    decisions.push(decision);
-    await saveDecisions(target, decisions);
+    const dir = path.join(target, DIR);
+    await fs.ensureDir(dir);
+    const file = path.join(dir, `${decision.id}-${slugify(decision.title)}.md`);
+    await fs.writeFile(file, serialize(decision));
     return decision;
 }

package/dist/utils/refinements.js

@@ -1,9 +1,49 @@
 import path from "node:path";
 import fs from "fs-extra";
-const STORE_FILENAME = "refinements.json";
-const STORE_DIR = "intelligence";
-export async function loadRefinements(target) {
-    const file = path.join(target, STORE_DIR, STORE_FILENAME);
+import matter from "gray-matter";
+const DIR = "intelligence/refinements";
+const LEGACY_STORE = "intelligence/refinements.json";
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function parseFile(raw) {
+    const { data, content } = matter(raw);
+    const note = content.trim();
+    if (!data.id || !note)
+        return null;
+    const scope = {};
+    if (data.issueType)
+        scope.issueType = String(data.issueType);
+    if (data.selector)
+        scope.selector = String(data.selector);
+    if (data.file)
+        scope.file = String(data.file);
+    return {
+        id: String(data.id),
+        timestamp: String(data.createdAt ?? data.timestamp ?? ""),
+        note,
+        scope: Object.keys(scope).length > 0 ? scope : undefined
+    };
+}
+function serialize(r) {
+    const fm = {
+        id: r.id,
+        createdAt: r.timestamp
+    };
+    if (r.scope?.issueType)
+        fm.issueType = r.scope.issueType;
+    if (r.scope?.selector)
+        fm.selector = r.scope.selector;
+    if (r.scope?.file)
+        fm.file = r.scope.file;
+    return matter.stringify(r.note, fm);
+}
+async function loadLegacy(target) {
+    const file = path.join(target, LEGACY_STORE);
     if (!(await fs.pathExists(file)))
         return [];
     try {
@@ -13,16 +53,49 @@ export async function loadRefinements(target) {
         return [];
     }
 }
-export async function saveRefinements(target, refinements) {
-    const dir = path.join(target, STORE_DIR);
-    await fs.ensureDir(dir);
-    const file = path.join(dir, STORE_FILENAME);
-    await fs.writeJson(file, refinements, { spaces: 2 });
+export async function loadRefinements(target) {
+    const dir = path.join(target, DIR);
+    const fromFiles = [];
+    if (await fs.pathExists(dir)) {
+        const entries = (await fs.readdir(dir)).filter((f) => f.endsWith(".md")).sort();
+        for (const entry of entries) {
+            const raw = await fs.readFile(path.join(dir, entry), "utf8");
+            const parsed = parseFile(raw);
+            if (parsed)
+                fromFiles.push({ ...parsed, sourcePath: `${DIR}/${entry}` });
+        }
+    }
+    // Dual read: surface legacy JSON entries that haven't been migrated yet.
+    const legacy = await loadLegacy(target);
+    const seen = new Set(fromFiles.map((r) => r.id));
+    for (const r of legacy) {
+        if (!seen.has(r.id))
+            fromFiles.push(r);
+    }
+    return fromFiles;
 }
-export async function appendRefinement(target, refinement) {
-    const current = await loadRefinements(target);
-    current.push(refinement);
-    await saveRefinements(target, current);
+function nextId(existing) {
+    let max = 0;
+    for (const r of existing) {
+        const m = /^REF-(\d+)$/.exec(r.id);
+        if (m)
+            max = Math.max(max, Number(m[1]));
+    }
+    return `REF-${String(max + 1).padStart(4, "0")}`;
+}
+export async function appendRefinement(target, input) {
+    const existing = await loadRefinements(target);
+    const refinement = {
+        id: nextId(existing),
+        timestamp: new Date().toISOString().slice(0, 10),
+        note: input.note,
+        scope: input.scope
+    };
+    const dir = path.join(target, DIR);
+    await fs.ensureDir(dir);
+    const file = path.join(dir, `${refinement.id}-${slugify(refinement.note)}.md`);
+    await fs.writeFile(file, serialize(refinement));
+    return refinement;
 }
 // Lightweight natural-language extractor. Recognises hints like:
 //   "Button radius should remain 2px for controls" -> issueType: radius-consistency

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whale-igniter",
-  "version": "1.5.1",
+  "version": "1.5.2",
   "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",
@@ -65,7 +65,8 @@
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "fs-extra": "^11.2.0",
-    "glob": "^10.4.5",
+    "glob": "^13.0.6",
+    "gray-matter": "^4.0.3",
     "ora": "^8.1.0",
     "postcss": "^8.4.47",
     "prompts": "^2.4.2",