wicked-brain 0.11.0 → 0.12.1

package/install.mjs

@@ -11,8 +11,44 @@ const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const skillsSource = join(__dirname, "skills");
 const home = homedir();
 
+// Claude-root candidate builder. Claude Code's config root is redirectable
+// via $CLAUDE_CONFIG_DIR (multi-tenant setups, alt-config layouts, corporate
+// home-dir overrides). Mirrors the 0.3.3 wicked-testing fix: env var is
+// authoritative when set; otherwise we probe ~/.claude + common alt-config
+// paths and install into each that carries Claude identity markers.
+function buildClaudeTarget(rootDir, source, { trusted = false } = {}) {
+  return {
+    name: "claude",
+    rootDir,
+    dir: join(rootDir, "skills"),
+    agentDir: join(rootDir, "agents"),
+    agentSubdir: "agents",
+    platform: "claude",
+    identityMarkers: ["settings.json", "plugins", "projects"],
+    source,
+    trusted,
+  };
+}
+
+function resolveClaudeCandidates() {
+  const envDir = process.env.CLAUDE_CONFIG_DIR;
+  if (envDir && typeof envDir === "string" && envDir.trim()) {
+    // Function replacement avoids `$&` etc. being interpreted as regex
+    // back-references if $HOME contains those literals (pathological but
+    // cheap to defend against — flagged by gemini on the sibling PRs).
+    const root = resolve(envDir.trim().replace(/^~/, () => home));
+    return [buildClaudeTarget(root, "env:CLAUDE_CONFIG_DIR", { trusted: true })];
+  }
+  return [
+    buildClaudeTarget(join(home, ".claude"),                "default"),
+    buildClaudeTarget(join(home, "alt-configs", ".claude"), "alt-configs"),
+    buildClaudeTarget(join(home, ".config", "claude"),      "xdg"),
+  ];
+}
+
+// Canonical non-claude targets. Claude is expanded dynamically via
+// resolveClaudeCandidates() below so CLI_TARGETS stays a flat spec.
 const CLI_TARGETS = [
-  { name: "claude",      dir: join(home, ".claude", "skills"),      agentDir: join(home, ".claude", "agents"),      agentSubdir: "agents", platform: "claude" },
   { name: "gemini",      dir: join(home, ".gemini", "skills"),      agentDir: join(home, ".gemini", "agents"),      agentSubdir: "agents", platform: "gemini" },
   { name: "copilot",     dir: join(home, ".github", "skills"),      agentDir: join(home, ".github", "agents"),      agentSubdir: "agents", platform: "copilot" },
   { name: "codex",       dir: join(home, ".codex", "skills"),       agentDir: join(home, ".codex", "agents"),       agentSubdir: "agents", platform: "codex" },
@@ -21,22 +57,61 @@ const CLI_TARGETS = [
   { name: "antigravity", dir: join(home, ".antigravity", "skills"), agentDir: join(home, ".antigravity", "rules"),  agentSubdir: "rules",  platform: "antigravity" },
 ];
 
+// Identity-marker gate for claude candidates. Without this, probing
+// ~/.claude, ~/alt-configs/.claude, and ~/.config/claude would install
+// into every path that happens to exist — risky if one was created by a
+// different tool. Env-var / --path targets are `trusted` and skip this.
+function claudeHasIdentityMarker(target) {
+  if (target.trusted) return true;
+  if (!existsSync(target.rootDir)) return false;
+  return (target.identityMarkers || []).some(m => existsSync(join(target.rootDir, m)));
+}
+
 console.log("wicked-brain installer\n");
 
 const args = argv.slice(2);
-const argValue = (a) => a.split("=")[1];
-const cliArg = args.find((a) => a.startsWith("--cli="));
-const pathArg = args.find((a) => a.startsWith("--path="));
+
+// Flag parser supporting both forms:
+//   --flag=value   (canonical)
+//   --flag value   (common shell muscle-memory; previously silently
+//                   dropped the value and fell through to default
+//                   detection — same bug that hit wicked-testing 0.3.2).
+// Narrow string-boolean coercion: literal "true" / "false" become
+// booleans so `--hooks=false` doesn't install hooks.
+const flagValue = (name) => {
+  const f = args.find(a => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (!f) return null;
+  let val;
+  if (f.includes("=")) {
+    // slice from the first '=' forward — split("=")[1] would truncate at
+    // the second '=' (e.g. --path=/volumes/build=artifacts would silently
+    // drop "=artifacts").
+    val = f.slice(f.indexOf("=") + 1);
+  } else {
+    const idx = args.indexOf(f);
+    const next = args[idx + 1];
+    val = (next && !next.startsWith("-")) ? next : true;
+  }
+  if (val === "false") return false;
+  if (val === "true")  return true;
+  return val;
+};
+
+const cliArg  = flagValue("cli");
+const pathArg = flagValue("path");
+
+// Validate --cli upfront — if the user passed a bare --cli or --cli=,
+// they misspoke and we should not silently fall through to "install
+// everywhere". Applies regardless of whether --path is also set.
+if (cliArg === true || cliArg === "") {
+  console.error("Error: --cli requires a value (e.g. --cli=claude or --cli claude)");
+  process.exit(1);
+}
 
 let targets;
 
-if (pathArg) {
-  const rawPath = argValue(pathArg);
-  if (!rawPath) {
-    console.error("Error: --path requires a value (e.g. --path=~/.claude)");
-    process.exit(1);
-  }
-  const customPath = resolve(rawPath.replace(/^~/, home));
+if (pathArg && typeof pathArg === "string" && pathArg !== "") {
+  const customPath = resolve(pathArg.replace(/^~/, () => home));
   // Strip leading dot to match CLI_TARGETS names (e.g. ".claude" → "claude")
   const dirName = basename(customPath).replace(/^\./, "");
   const knownPlatform = CLI_TARGETS.find((t) => t.name === dirName);
@@ -48,19 +123,33 @@ if (pathArg) {
     platform: knownPlatform?.platform ?? dirName,
   }];
   console.log(`Custom path: ${customPath}\n`);
+} else if (pathArg === true || pathArg === "") {
+  console.error("Error: --path requires a value (e.g. --path=~/.claude or --path ~/.claude)");
+  process.exit(1);
 } else {
-  // Detect which CLIs are installed by checking if parent dir exists
-  const detected = CLI_TARGETS.filter((t) => existsSync(resolve(t.dir, "..")));
+  // Build the detection set: expanded claude candidates (env var OR alt-config
+  // probes) + all non-claude targets. Claude candidates pass an identity-marker
+  // check so we don't install into a bare ~/.claude that belongs to some other
+  // tool. Non-claude targets keep the original parent-dir-exists heuristic.
+  const claudeDetected = resolveClaudeCandidates().filter(claudeHasIdentityMarker);
+  const otherDetected  = CLI_TARGETS.filter((t) => existsSync(resolve(t.dir, "..")));
+  const detected = [...claudeDetected, ...otherDetected];
 
   if (detected.length === 0) {
     console.log("No supported AI CLIs detected. Supported: claude, gemini, copilot, codex, cursor, kiro, antigravity");
-    console.log("Install skills manually by copying the skills/ directory.");
+    console.log("Install skills manually by copying the skills/ directory, or set CLAUDE_CONFIG_DIR.");
     process.exit(1);
   }
 
-  console.log(`Detected CLIs: ${detected.map((d) => d.name).join(", ")}\n`);
+  // Annotate claude candidates with their source when more than one was
+  // detected, so the log is not ambiguous.
+  const claudeCount = claudeDetected.length;
+  const label = (d) => d.name === "claude" && claudeCount > 1 && d.source
+    ? `${d.name}[${d.source}]`
+    : d.name;
+  console.log(`Detected CLIs: ${detected.map(label).join(", ")}\n`);
 
-  const cliFilter = cliArg ? argValue(cliArg).split(",") : null;
+  const cliFilter = (typeof cliArg === "string" && cliArg !== "") ? cliArg.split(",") : null;
   targets = cliFilter ? detected.filter((d) => cliFilter.includes(d.name)) : detected;
 }
 
@@ -106,8 +195,10 @@ for (const target of targets) {
   console.log(`  Installed ${agentCount} agents to ${target.agentDir}`);
 }
 
-// Optional hook installation (--hooks flag)
-const installHooks = args.includes("--hooks");
+// Optional hook installation (--hooks flag). Goes through flagValue so
+// `--hooks=false` correctly disables; bare `--hooks` and `--hooks=true`
+// both enable (flagValue coerces "true"/"false" literals to booleans).
+const installHooks = flagValue("hooks") === true;
 
 if (installHooks) {
   console.log("\nInstalling hooks...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/bin/wicked-brain-server.mjs

@@ -207,6 +207,17 @@ const actions = {
   tag_frequency: () => ({ tags: db.tagFrequency() }),
   search_misses: (p) => ({ misses: db.searchMisses(p) }),
   wiki_list: (p) => db.wikiList(p),
+  verify_wiki: (p = {}) => {
+    const result = db.verifyWiki(p);
+    emitEvent("wicked.wiki.verified", "brain.wiki", {
+      brain_id: brainId,
+      total: result.summary.total,
+      stale: result.summary.stale,
+      orphaned: result.summary.orphaned,
+      unverifiable: result.summary.unverifiable,
+    });
+    return result;
+  },
   // LSP actions
   "lsp-health": () => lsp.health(),
   "lsp-symbols": (p) => lsp.symbols(p),

package/server/lib/sqlite-search.mjs

@@ -1,7 +1,32 @@
 import Database from "better-sqlite3";
 import { parseWikilinks } from "./wikilinks.mjs";
-import { parseFrontmatterBlock } from "./frontmatter.mjs";
+import { parseFrontmatterBlock, extractFrontmatter } from "./frontmatter.mjs";
 import { statSync } from "node:fs";
+import { createHash } from "node:crypto";
+
+/**
+ * Parse a source_hashes entry of the form "{chunk_path}: {hash}". Returns
+ * null if the shape doesn't match — malformed entries are skipped rather
+ * than blocking the whole verify call.
+ */
+function parseHashEntry(raw) {
+  if (typeof raw !== "string") return null;
+  const idx = raw.indexOf(":");
+  if (idx < 0) return null;
+  const chunkPath = raw.slice(0, idx).trim();
+  const hash = raw.slice(idx + 1).trim();
+  if (!chunkPath || !hash) return null;
+  return { chunkPath, hash };
+}
+
+/**
+ * First 8 hex chars of SHA-256 over the chunk body (frontmatter stripped).
+ * Matches the convention wicked-brain:compile uses when writing source_hashes.
+ */
+function chunkBodyHash(content) {
+  const { body } = extractFrontmatter(content ?? "");
+  return createHash("sha256").update(body).digest("hex").slice(0, 8);
+}
 
 /**
  * Extracts body text from a document, stripping YAML frontmatter.
@@ -258,7 +283,8 @@ export class SqliteSearch {
         canonical_for TEXT,
         refs TEXT,
         translation_of TEXT,
-        version_of TEXT
+        version_of TEXT,
+        last_verified_at INTEGER
       );
 
       CREATE TABLE IF NOT EXISTS canonical_ownership (
@@ -402,6 +428,14 @@ export class SqliteSearch {
       currentVersion = 5;
     }
 
+    // Migration 6: add last_verified_at for wiki staleness detection
+    if (currentVersion < 6) {
+      try { this.#db.prepare(`SELECT last_verified_at FROM documents LIMIT 0`).get(); } catch {
+        this.#db.exec(`ALTER TABLE documents ADD COLUMN last_verified_at INTEGER`);
+      }
+      currentVersion = 6;
+    }
+
     // Persist the current version
     this.#db.exec(`DELETE FROM _schema_version`);
     this.#db.prepare(`INSERT INTO _schema_version (version) VALUES (?)`).run(currentVersion);
@@ -540,7 +574,7 @@ export class SqliteSearch {
    */
   getDocument(id) {
     const row = this.#db
-      .prepare(`SELECT id, path, content, frontmatter, brain_id, indexed_at, content_hash, canonical_for, refs FROM documents WHERE id = ?`)
+      .prepare(`SELECT id, path, content, frontmatter, brain_id, indexed_at, content_hash, canonical_for, refs, last_verified_at FROM documents WHERE id = ?`)
       .get(id);
     return this.#hydrateDocumentRow(row);
   }
@@ -551,7 +585,7 @@ export class SqliteSearch {
    */
   getDocumentByPath(path) {
     const row = this.#db
-      .prepare(`SELECT id, path, content, frontmatter, brain_id, indexed_at, content_hash, canonical_for, refs FROM documents WHERE path = ? LIMIT 1`)
+      .prepare(`SELECT id, path, content, frontmatter, brain_id, indexed_at, content_hash, canonical_for, refs, last_verified_at FROM documents WHERE path = ? LIMIT 1`)
       .get(path);
     return this.#hydrateDocumentRow(row);
   }
@@ -568,6 +602,7 @@ export class SqliteSearch {
       content_hash: row.content_hash,
       canonical_for: row.canonical_for ? JSON.parse(row.canonical_for) : [],
       references: row.refs ? JSON.parse(row.refs) : [],
+      last_verified_at: row.last_verified_at ?? null,
     };
   }
 
@@ -1259,6 +1294,102 @@ export class SqliteSearch {
     return { articles };
   }
 
+  /**
+   * Verify wiki articles against the current hashes of the chunks they claim
+   * to synthesize. Returns a per-article classification plus a summary.
+   *
+   * See docs/specs/2026-04-17-wiki-staleness-detection.md for the contract.
+   * Read-only w.r.t. content: the only mutation is stamping
+   * documents.last_verified_at for each article scanned.
+   */
+  verifyWiki({ path = null } = {}) {
+    let rows;
+    if (path) {
+      rows = this.#db.prepare(`
+        SELECT id, path, content, frontmatter
+        FROM documents
+        WHERE path = ? AND path LIKE 'wiki/%'
+      `).all(path);
+    } else {
+      rows = this.#db.prepare(`
+        SELECT id, path, content, frontmatter
+        FROM documents
+        WHERE path LIKE 'wiki/%'
+        ORDER BY path
+      `).all();
+    }
+
+    const summary = { total: 0, fresh: 0, stale: 0, orphaned: 0, unverifiable: 0 };
+    const articles = [];
+    const now = Date.now();
+    const stampVerified = this.#db.prepare(
+      `UPDATE documents SET last_verified_at = ? WHERE id = ?`,
+    );
+
+    for (const row of rows) {
+      summary.total++;
+      const classification = this.#classifyWikiArticle(row);
+      articles.push({
+        path: row.path,
+        status: classification.status,
+        source_count: classification.source_count,
+        matched: classification.matched,
+        mismatched: classification.mismatched,
+        missing: classification.missing,
+        last_verified_at: now,
+      });
+      summary[classification.status]++;
+      stampVerified.run(now, row.id);
+    }
+
+    return { articles, summary };
+  }
+
+  #classifyWikiArticle(row) {
+    const fmBlock = row.frontmatter || SqliteSearch.#extractFrontmatter(row.content) || "";
+    let fmData = {};
+    try { fmData = parseFrontmatterBlock(fmBlock); } catch { fmData = {}; }
+    const hashEntries = Array.isArray(fmData.source_hashes) ? fmData.source_hashes : [];
+    if (hashEntries.length === 0) {
+      return { status: "unverifiable", source_count: 0, matched: 0, mismatched: [], missing: [] };
+    }
+
+    const mismatched = [];
+    const missing = [];
+    let matched = 0;
+
+    for (const entry of hashEntries) {
+      const parsed = parseHashEntry(entry);
+      if (!parsed) continue; // malformed line — skip silently
+      const chunk = this.#db.prepare(
+        `SELECT content FROM documents WHERE path = ?`,
+      ).get(parsed.chunkPath);
+      if (!chunk) {
+        missing.push(parsed.chunkPath);
+        continue;
+      }
+      const currentHash = chunkBodyHash(chunk.content);
+      if (currentHash === parsed.hash) {
+        matched++;
+      } else {
+        mismatched.push(parsed.chunkPath);
+      }
+    }
+
+    const source_count = hashEntries.length;
+    let status;
+    if (mismatched.length > 0) {
+      status = "stale";
+    } else if (missing.length === source_count) {
+      status = "orphaned";
+    } else if (missing.length > 0) {
+      status = "stale";
+    } else {
+      status = "fresh";
+    }
+    return { status, source_count, matched, mismatched, missing };
+  }
+
   /**
    * Parse tags from frontmatter string.
    * Supports space-separated inline, JSON array, and YAML block list formats.

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.11.0",
+  "version": "0.12.1",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

package/skills/wicked-brain-status/SKILL.md

@@ -83,7 +83,21 @@ Depth 0 plus:
   ```
   Group results by path prefix (e.g., `chunks/extracted/`, `wiki/`) to show recent activity distribution.
 - List the top 10 most common tags
-- Flag any staleness warnings (sources modified after last ingest)
+- Flag wiki staleness warnings by calling `verify_wiki`:
+  ```bash
+  curl -s -X POST http://localhost:{port}/api \
+    -H "Content-Type: application/json" \
+    -d '{"action":"verify_wiki","params":{}}'
+  ```
+  Report one line per non-fresh bucket — only emit the lines where the count is > 0:
+  ```
+  ⚠ Wiki staleness: {stale} stale / {orphaned} orphaned / {unverifiable} unverifiable (of {total} articles)
+  ```
+  `stale` = at least one referenced chunk changed or is missing. `orphaned` =
+  every referenced chunk is missing from the index. `unverifiable` = article
+  predates `source_hashes` frontmatter. Suggest running `wicked-brain:compile`
+  to refresh stale articles.
+  If `total == 0` (brain has no wiki yet), skip the line entirely.
 
 **Convergence Debt:**
 Detect chunks that are frequently accessed but have never been compiled into wiki articles: