sanook-cli 0.5.1 → 0.5.5

package/dist/brain-repair.js

@@ -0,0 +1,280 @@
+import { mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FOLDERS } from './brain.js';
+import { checkBrainFolders } from './brain-doctor.js';
+import { inferParentRelPath } from './brain-new.js';
+import { extractPackDescription, normalizePackName as normalizeContextPackName } from './brain-pack.js';
+const ROOT_FILES_WITHOUT_PARENT = new Set(['Home.md', 'README.md', 'CLAUDE.md', 'GEMINI.md', 'AGENTS.md', 'SANOOK.md']);
+const ROOT_FILES_WITHOUT_UP = ROOT_FILES_WITHOUT_PARENT;
+const SKIP_DIRS = new Set(['.git', '.obsidian', 'node_modules', 'Shared/Context7-Docs']);
+const PURPOSE_PLACEHOLDER = '> _(purpose pending — fill in)_\n\n';
+export function parseBrainRepairArgs(args) {
+    for (const arg of args) {
+        if (arg === '--dry-run')
+            continue;
+        return { ok: false, message: `ไม่รู้จัก option: ${arg}` };
+    }
+    return { ok: true, dryRun: args.includes('--dry-run') };
+}
+export function planPurposeFix(relPath, content) {
+    if (/^>\s+/m.test(content))
+        return undefined;
+    return {
+        id: 'repair.purpose-blockquote',
+        relPath,
+        kind: 'markdown',
+        message: 'Add purpose blockquote after frontmatter.',
+    };
+}
+export function planParentFix(relPath, content) {
+    if (ROOT_FILES_WITHOUT_PARENT.has(relPath))
+        return undefined;
+    if (/^---[\s\S]*?^parent:/m.test(content))
+        return undefined;
+    const parent = inferParentRelPath(relPath);
+    return {
+        id: 'repair.parent-frontmatter',
+        relPath,
+        kind: 'markdown',
+        message: `Add parent frontmatter -> [[${parent}]]`,
+    };
+}
+export function planUpLinkFix(relPath, content) {
+    if (ROOT_FILES_WITHOUT_UP.has(relPath))
+        return undefined;
+    if (content.includes('up:: [['))
+        return undefined;
+    const parent = inferParentRelPath(relPath);
+    return {
+        id: 'repair.up-link',
+        relPath,
+        kind: 'markdown',
+        message: `Append up:: [[${parent}]]`,
+    };
+}
+export function applyPurposeFix(content) {
+    if (/^>\s+/m.test(content))
+        return content;
+    const match = content.match(/^---[\s\S]*?---\n?/);
+    if (match)
+        return content.replace(match[0], `${match[0]}${PURPOSE_PLACEHOLDER}`);
+    return `${PURPOSE_PLACEHOLDER}${content}`;
+}
+export function applyParentFix(content, relPath) {
+    if (/^---[\s\S]*?^parent:/m.test(content))
+        return content;
+    const parent = inferParentRelPath(relPath);
+    const parentLine = `parent: "[[${parent}]]"`;
+    const match = content.match(/^---\n([\s\S]*?)---\n/);
+    if (!match)
+        return `---\n${parentLine}\n---\n\n${content}`;
+    return content.replace(/^---\n/, `---\n${parentLine}\n`);
+}
+export function applyUpLinkFix(content, relPath) {
+    if (content.includes('up:: [['))
+        return content;
+    const parent = inferParentRelPath(relPath);
+    return `${content.trimEnd()}\n\nup:: [[${parent}]]\n`;
+}
+export function applyMarkdownRepairs(relPath, content) {
+    let next = content;
+    const applied = [];
+    if (planPurposeFix(relPath, next)) {
+        next = applyPurposeFix(next);
+        applied.push('purpose-blockquote');
+    }
+    if (planParentFix(relPath, next)) {
+        next = applyParentFix(next, relPath);
+        applied.push('parent-frontmatter');
+    }
+    if (planUpLinkFix(relPath, next)) {
+        next = applyUpLinkFix(next, relPath);
+        applied.push('up-link');
+    }
+    return { content: next, applied };
+}
+export function planContextPackIndexFix(packName, indexContent) {
+    const link = `[[Shared/Context-Packs/${packName}]]`;
+    if (indexContent.includes(link))
+        return undefined;
+    return {
+        id: 'repair.context-pack-index',
+        relPath: 'Shared/Context-Packs/_Index.md',
+        kind: 'index',
+        message: `Link ${packName} from Context-Packs/_Index.md`,
+    };
+}
+export function applyContextPackIndexFix(indexContent, packName, packContent) {
+    const link = `[[Shared/Context-Packs/${packName}]]`;
+    if (indexContent.includes(link))
+        return indexContent;
+    const description = extractBlockquotePurpose(packContent) || 'context pack';
+    const line = `- ${link} — ${description}`;
+    const marker = '\n## Use Rule';
+    if (indexContent.includes(marker))
+        return indexContent.replace(marker, `\n${line}\n${marker}`);
+    const upMarker = '\nup:: [[Shared/_Index]]';
+    if (indexContent.includes(upMarker))
+        return indexContent.replace(upMarker, `\n${line}\n${upMarker}`);
+    return `${indexContent.trimEnd()}\n${line}\n`;
+}
+export async function collectRepairActions(brainPath, expectedFolders = FOLDERS.map((folder) => folder.dir)) {
+    const actions = [];
+    const folderCheck = await checkBrainFolders(brainPath, expectedFolders);
+    for (const missing of folderCheck.details ?? []) {
+        actions.push({
+            id: 'repair.missing-folder',
+            relPath: missing,
+            kind: 'folder',
+            message: `Create missing folder: ${missing}`,
+        });
+    }
+    for (const relPath of await listMarkdown(brainPath)) {
+        const content = await readText(join(brainPath, relPath));
+        for (const plan of [planPurposeFix, planParentFix, planUpLinkFix]) {
+            const action = plan(relPath, content);
+            if (action)
+                actions.push(action);
+        }
+    }
+    const packsDir = join(brainPath, 'Shared', 'Context-Packs');
+    const indexPath = join(packsDir, '_Index.md');
+    const indexContent = await readText(indexPath);
+    let entries;
+    try {
+        entries = await readdir(packsDir, { withFileTypes: true });
+    }
+    catch {
+        return actions;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.md') || entry.name === '_Index.md')
+            continue;
+        const packName = normalizeContextPackName(entry.name);
+        const action = planContextPackIndexFix(packName, indexContent);
+        if (action)
+            actions.push(action);
+    }
+    return actions;
+}
+export async function repairBrain(options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const warnings = [];
+    const brainPath = options.brainPath;
+    if (!brainPath) {
+        return { ok: false, dryRun, actions: [], applied: [], warnings: ['No second-brain path is configured.'] };
+    }
+    if (!(await pathExistsAsDir(brainPath))) {
+        return { ok: false, brainPath, dryRun, actions: [], applied: [], warnings: ['Configured second-brain path does not exist or is not a directory.'] };
+    }
+    const actions = await collectRepairActions(brainPath, options.expectedFolders);
+    if (dryRun) {
+        return { ok: true, brainPath, dryRun, actions, applied: [], warnings };
+    }
+    const applied = [];
+    const markdownUpdates = new Map();
+    for (const action of actions) {
+        if (action.kind === 'folder') {
+            await mkdir(join(brainPath, action.relPath), { recursive: true });
+            applied.push(`${action.relPath}: created folder`);
+            continue;
+        }
+        if (action.kind === 'index' && action.id === 'repair.context-pack-index') {
+            const indexPath = join(brainPath, action.relPath);
+            const indexContent = await readText(indexPath);
+            if (!indexContent) {
+                warnings.push(`Skipped ${action.relPath}: index file missing.`);
+                continue;
+            }
+            const packName = action.message.match(/Link ([^\s]+) from/)?.[1];
+            if (!packName)
+                continue;
+            const packContent = await readText(join(brainPath, 'Shared', 'Context-Packs', `${packName}.md`));
+            const next = applyContextPackIndexFix(indexContent, packName, packContent);
+            if (next !== indexContent) {
+                await writeFile(indexPath, next, 'utf8');
+                applied.push(`${action.relPath}: linked ${packName}`);
+            }
+            continue;
+        }
+        if (action.kind === 'markdown') {
+            const current = markdownUpdates.get(action.relPath)?.content ?? (await readText(join(brainPath, action.relPath)));
+            const repaired = applyMarkdownRepairs(action.relPath, current);
+            if (repaired.applied.length) {
+                const prior = markdownUpdates.get(action.relPath)?.applied ?? [];
+                markdownUpdates.set(action.relPath, { content: repaired.content, applied: uniqueSorted([...prior, ...repaired.applied]) });
+            }
+        }
+    }
+    for (const [relPath, update] of markdownUpdates) {
+        await writeFile(join(brainPath, relPath), update.content, 'utf8');
+        applied.push(`${relPath}: ${update.applied.join(', ')}`);
+    }
+    return { ok: true, brainPath, dryRun, actions, applied, warnings };
+}
+export function formatBrainRepairReport(report) {
+    const lines = ['Sanook brain repair', `vault: ${report.brainPath ?? '(not configured)'}`];
+    lines.push(`mode: ${report.dryRun ? 'dry-run' : 'apply'}`);
+    lines.push(`planned: ${report.actions.length} fix(es)`);
+    for (const action of report.actions) {
+        lines.push(`- [${action.id}] ${action.relPath} — ${action.message}`);
+    }
+    if (!report.dryRun) {
+        lines.push(`applied: ${report.applied.length}`);
+        for (const item of report.applied)
+            lines.push(`  ✓ ${item}`);
+    }
+    for (const warning of report.warnings)
+        lines.push(`warning: ${warning}`);
+    return lines.join('\n');
+}
+async function listMarkdown(root) {
+    const out = [];
+    async function walk(abs, rel) {
+        let entries;
+        try {
+            entries = await readdir(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name) || SKIP_DIRS.has(childRel))
+                    continue;
+                await walk(join(abs, entry.name), childRel);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                out.push(childRel);
+            }
+        }
+    }
+    await walk(root, '');
+    return out.sort();
+}
+async function pathExistsAsDir(path) {
+    try {
+        const { stat } = await import('node:fs/promises');
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+function extractBlockquotePurpose(content) {
+    const body = content.replace(/^---[\s\S]*?---\n?/, '');
+    const match = body.match(/^>\s*(.+)$/m);
+    return match?.[1]?.trim() ?? '';
+}
+function uniqueSorted(values) {
+    return [...new Set(values.filter(Boolean))].sort((a, b) => a.localeCompare(b));
+}

package/dist/brain-review.js

@@ -0,0 +1,382 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { listFinalGateFiles, validateFinalGateContent } from './brain-final.js';
+import { normalize } from './memory-store.js';
+import { INDEX_PATH, sanitizeManifest } from './search/store.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_MEMORY_INBOX_MAX_AGE_DAYS = 14;
+const DEFAULT_CONTEXT_PACK_MAX_AGE_DAYS = 90;
+const DEFAULT_EVAL_FRESHNESS_TOLERANCE_MS = 60 * 1000;
+const DETAIL_LIMIT = 25;
+const ROOT_FILES_WITHOUT_UP = new Set(['Home.md', 'README.md', 'CLAUDE.md', 'GEMINI.md', 'AGENTS.md', 'SANOOK.md']);
+const ROOT_FILES_WITHOUT_PARENT = ROOT_FILES_WITHOUT_UP;
+const SKIP_DIRS = new Set(['.git', '.obsidian', 'node_modules', 'Shared/Context7-Docs']);
+const NEGATION_TOKENS = new Set([
+    'no',
+    'not',
+    'never',
+    'without',
+    'disable',
+    'disabled',
+    'false',
+    'ไม่',
+    'ห้าม',
+    'เลิก',
+    'ปิด',
+    'ไม่ได้',
+    'ไม่ชอบ',
+]);
+export function parseBrainReviewArgs(args) {
+    let scanMarkdownHygiene = true;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--no-hygiene') {
+            scanMarkdownHygiene = false;
+        }
+        else if (a === '--hygiene') {
+            scanMarkdownHygiene = true;
+        }
+        else {
+            return { ok: false, message: `ไม่รู้จัก option: ${a}` };
+        }
+    }
+    return { ok: true, value: { scanMarkdownHygiene } };
+}
+function result(id, title, findings, message, fail = false, path) {
+    const status = fail ? 'fail' : findings.length ? 'warn' : 'pass';
+    return { id, title, status, message, path, findings: findings.length ? findings : undefined };
+}
+function normalizeCandidate(line) {
+    return normalize(line.replace(/^-\s*/, '').replace(/\s+/g, ' ')).trim();
+}
+function tokensForCandidate(line) {
+    return new Set(normalizeCandidate(line)
+        .split(/\s+/)
+        .filter((token) => token.length > 1 && !NEGATION_TOKENS.has(token)));
+}
+function hasNegation(line) {
+    const normalized = normalizeCandidate(line);
+    return [...NEGATION_TOKENS].some((token) => normalized.includes(token));
+}
+function sectionBullets(content, heading) {
+    const lines = content.split('\n');
+    const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading.toLowerCase()}`);
+    if (start < 0)
+        return [];
+    const out = [];
+    for (const line of lines.slice(start + 1)) {
+        if (/^#{1,6}\s+/.test(line.trim()))
+            break;
+        const trimmed = line.trim();
+        if (trimmed.startsWith('- ') && !trimmed.includes('_('))
+            out.push(trimmed);
+    }
+    return out;
+}
+function overlap(a, b) {
+    if (!a.size || !b.size)
+        return 0;
+    let shared = 0;
+    for (const token of a)
+        if (b.has(token))
+            shared++;
+    return shared / Math.min(a.size, b.size);
+}
+async function pathExistsAsDir(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+async function mtimeMs(path) {
+    try {
+        return (await stat(path)).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+async function listMarkdown(root) {
+    const out = [];
+    async function walk(abs, rel) {
+        let entries;
+        try {
+            entries = await readdir(abs, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('.') || SKIP_DIRS.has(entry.name) || SKIP_DIRS.has(childRel))
+                    continue;
+                await walk(join(abs, entry.name), childRel);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                out.push(childRel);
+            }
+        }
+    }
+    await walk(root, '');
+    return out.sort();
+}
+async function readManifest(indexPath) {
+    try {
+        const raw = JSON.parse(await readFile(indexPath, 'utf8'));
+        return sanitizeManifest(raw.manifest);
+    }
+    catch {
+        return null;
+    }
+}
+async function checkMemoryInbox(brainPath, nowMs, maxAgeDays) {
+    const path = join(brainPath, 'Shared', 'Memory-Inbox', 'memory-inbox.md');
+    const content = await readText(path);
+    if (!content) {
+        return result('review.memory-inbox', 'Memory-Inbox curation', [{ message: 'Memory-Inbox file is missing.', path }], 'Memory-Inbox is missing.', true, path);
+    }
+    const candidates = [...sectionBullets(content, 'New Candidates'), ...sectionBullets(content, 'Needs Merge')];
+    const findings = [];
+    const seen = new Map();
+    const duplicates = [];
+    for (const candidate of candidates) {
+        const key = normalizeCandidate(candidate);
+        if (!key)
+            continue;
+        if (seen.has(key))
+            duplicates.push(candidate);
+        else
+            seen.set(key, candidate);
+    }
+    if (duplicates.length) {
+        findings.push({ message: `${duplicates.length} duplicate Memory-Inbox candidate(s).`, path, details: duplicates.slice(0, DETAIL_LIMIT) });
+    }
+    const needsMerge = sectionBullets(content, 'Needs Merge');
+    if (needsMerge.length) {
+        findings.push({ message: `${needsMerge.length} Memory-Inbox item(s) are waiting in Needs Merge.`, path, details: needsMerge.slice(0, DETAIL_LIMIT) });
+    }
+    const possibleContradictions = [];
+    for (let i = 0; i < candidates.length; i++) {
+        for (let j = i + 1; j < candidates.length; j++) {
+            if (hasNegation(candidates[i]) === hasNegation(candidates[j]))
+                continue;
+            const score = overlap(tokensForCandidate(candidates[i]), tokensForCandidate(candidates[j]));
+            if (score >= 0.6)
+                possibleContradictions.push(`${candidates[i]} <> ${candidates[j]}`);
+        }
+    }
+    if (possibleContradictions.length) {
+        findings.push({
+            message: `${possibleContradictions.length} possible contradictory Memory-Inbox pair(s).`,
+            path,
+            details: possibleContradictions.slice(0, DETAIL_LIMIT),
+        });
+    }
+    const ageDays = Math.floor((nowMs - (await mtimeMs(path))) / DAY_MS);
+    if (candidates.length && ageDays > maxAgeDays) {
+        findings.push({ message: `Memory-Inbox has ${candidates.length} candidate(s) and was last touched ${ageDays} days ago.`, path });
+    }
+    return result('review.memory-inbox', 'Memory-Inbox curation', findings, candidates.length ? `${candidates.length} candidate(s) reviewed.` : 'Memory-Inbox has no active candidates.', false, path);
+}
+async function checkContextPacks(brainPath, nowMs, maxAgeDays) {
+    const dir = join(brainPath, 'Shared', 'Context-Packs');
+    const indexPath = join(dir, '_Index.md');
+    const index = await readText(indexPath);
+    const findings = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return result('review.context-packs', 'Context pack curation', [{ message: 'Context-Packs directory is missing.', path: dir }], 'Context-Packs directory is missing.', true, dir);
+    }
+    if (!index)
+        findings.push({ message: 'Context-Packs index is missing.', path: indexPath });
+    const packs = entries.filter((entry) => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_Index.md');
+    for (const pack of packs) {
+        const path = join(dir, pack.name);
+        const content = await readText(path);
+        const missingSections = ['## Load Order', '## Done Criteria'].filter((section) => !content.includes(section));
+        if (missingSections.length) {
+            findings.push({ message: `${pack.name} is missing expected section(s).`, path, details: missingSections });
+        }
+        const link = `[[Shared/Context-Packs/${pack.name.replace(/\.md$/i, '')}]]`;
+        if (index && !index.includes(link))
+            findings.push({ message: `${pack.name} is not linked from Context-Packs index.`, path: indexPath });
+        const ageDays = Math.floor((nowMs - (await mtimeMs(path))) / DAY_MS);
+        if (ageDays > maxAgeDays)
+            findings.push({ message: `${pack.name} has not been touched for ${ageDays} days.`, path });
+    }
+    return result('review.context-packs', 'Context pack curation', findings, packs.length ? `${packs.length} context pack(s) reviewed.` : 'No context packs found.', false, dir);
+}
+async function checkSessionIndexCoverage(brainPath, indexPath) {
+    const sessionsDir = join(brainPath, 'Sessions');
+    let entries;
+    try {
+        entries = await readdir(sessionsDir, { withFileTypes: true });
+    }
+    catch {
+        return result('review.session-index', 'Session index coverage', [{ message: 'Sessions directory is missing.', path: sessionsDir }], 'Sessions directory is missing.', true, sessionsDir);
+    }
+    const sessions = entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.md') && entry.name !== '_Index.md')
+        .map((entry) => `Sessions/${entry.name}`)
+        .sort();
+    if (!sessions.length)
+        return result('review.session-index', 'Session index coverage', [], 'No session notes to check.', false, sessionsDir);
+    const manifest = await readManifest(indexPath);
+    if (!manifest) {
+        return result('review.session-index', 'Session index coverage', [{ message: 'Search index is missing or unreadable; run `sanook index`.', path: indexPath }], `${sessions.length} session note(s) found, but no readable index manifest exists.`, false, indexPath);
+    }
+    const missing = sessions.filter((session) => !manifest[session]);
+    return result('review.session-index', 'Session index coverage', missing.length ? [{ message: `${missing.length} session note(s) are missing from the search manifest.`, path: indexPath, details: missing.slice(0, DETAIL_LIMIT) }] : [], `${sessions.length} session note(s) checked against the search manifest.`, false, indexPath);
+}
+async function frameworkFiles(brainPath) {
+    const paths = ['SANOOK.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'Vault Structure Map.md', 'Shared/AI-Context-Index.md'];
+    for (const rel of await listMarkdown(join(brainPath, 'Shared', 'Rules')))
+        paths.push(`Shared/Rules/${rel}`);
+    for (const rel of await listMarkdown(join(brainPath, 'Shared', 'Context-Packs')))
+        paths.push(`Shared/Context-Packs/${rel}`);
+    return paths;
+}
+async function newest(paths, brainPath) {
+    let best = { rel: '', mtime: 0 };
+    for (const rel of paths) {
+        const mt = await mtimeMs(join(brainPath, rel));
+        if (mt > best.mtime)
+            best = { rel, mtime: mt };
+    }
+    return best;
+}
+async function checkEvalFreshness(brainPath, toleranceMs) {
+    const evalFiles = ['Evals/second-brain-benchmarks.md', 'Evals/retrieval-eval.md', 'Evals/quality-ledger.md'];
+    const findings = [];
+    for (const rel of evalFiles) {
+        if (!(await mtimeMs(join(brainPath, rel))))
+            findings.push({ message: `Missing eval file: ${rel}`, path: join(brainPath, rel) });
+    }
+    if (findings.length) {
+        return result('review.eval-freshness', 'Eval freshness after framework changes', findings, 'Eval files are incomplete.', true, join(brainPath, 'Evals'));
+    }
+    const newestFramework = await newest(await frameworkFiles(brainPath), brainPath);
+    const newestEval = await newest(evalFiles, brainPath);
+    if (newestFramework.mtime > newestEval.mtime + toleranceMs) {
+        findings.push({
+            message: 'Framework/context files are newer than eval evidence; rerun `sanook brain eval` and update the ledger if behavior changed.',
+            details: [`newest framework: ${newestFramework.rel}`, `newest eval: ${newestEval.rel}`],
+        });
+    }
+    return result('review.eval-freshness', 'Eval freshness after framework changes', findings, 'Framework files and eval evidence compared.', false, join(brainPath, 'Evals'));
+}
+async function checkFinalGates(brainPath) {
+    const findings = [];
+    for (const rel of ['Templates/final.md', 'Templates/final-lite.md']) {
+        const content = await readText(join(brainPath, rel));
+        if (!content) {
+            findings.push({ message: `Missing final gate template: ${rel}`, path: join(brainPath, rel) });
+            continue;
+        }
+        const missing = ['## 1. Objective / DoD Lock', '## 4. Evidence Matrix', '## Final Verdict'].filter((section) => !content.includes(section));
+        if (missing.length)
+            findings.push({ message: `${rel} is missing expected final gate section(s).`, path: join(brainPath, rel), details: missing });
+    }
+    const gates = await listFinalGateFiles(brainPath);
+    for (const gate of gates) {
+        const validation = validateFinalGateContent(gate.content);
+        if (!validation.ok) {
+            findings.push({
+                message: `${gate.relPath} has incomplete final gate evidence.`,
+                path: gate.path,
+                details: validation.warnings.slice(0, DETAIL_LIMIT),
+            });
+        }
+    }
+    return result('review.final-gates', 'Final gate evidence', findings, gates.length ? `${gates.length} final gate note(s) checked.` : 'Final gate templates checked; no session final gates found.', false, join(brainPath, 'Templates'));
+}
+async function checkMarkdownHygiene(brainPath) {
+    const markdown = await listMarkdown(brainPath);
+    const missingPurpose = [];
+    const missingParent = [];
+    const missingUp = [];
+    for (const rel of markdown) {
+        const content = await readText(join(brainPath, rel));
+        if (!/^>\s+/m.test(content))
+            missingPurpose.push(rel);
+        if (!ROOT_FILES_WITHOUT_PARENT.has(rel) && !/^---[\s\S]*?^parent:/m.test(content))
+            missingParent.push(rel);
+        if (!ROOT_FILES_WITHOUT_UP.has(rel) && !content.includes('up:: [['))
+            missingUp.push(rel);
+    }
+    const findings = [];
+    if (missingPurpose.length)
+        findings.push({ message: `${missingPurpose.length} markdown file(s) have no purpose blockquote.`, details: missingPurpose.slice(0, DETAIL_LIMIT) });
+    if (missingParent.length)
+        findings.push({ message: `${missingParent.length} markdown file(s) have no parent frontmatter.`, details: missingParent.slice(0, DETAIL_LIMIT) });
+    if (missingUp.length)
+        findings.push({ message: `${missingUp.length} markdown file(s) have no up:: graph link.`, details: missingUp.slice(0, DETAIL_LIMIT) });
+    return result('review.markdown-hygiene', 'Markdown routing hygiene', findings, `${markdown.length} markdown file(s) scanned.`, false, brainPath);
+}
+export async function reviewBrain(options = {}) {
+    const brainPath = options.brainPath;
+    if (!brainPath) {
+        return {
+            ok: false,
+            checks: [
+                result('review.configured', 'Second-brain path configured', [{ message: 'No second-brain path is configured.' }], 'Run `sanook brain init [path]` first.', true),
+            ],
+        };
+    }
+    if (!(await pathExistsAsDir(brainPath))) {
+        return {
+            ok: false,
+            brainPath,
+            checks: [
+                result('review.path', 'Second-brain path exists', [{ message: 'Configured second-brain path does not exist or is not a directory.', path: brainPath }], 'Configured brainPath is not usable.', true, brainPath),
+            ],
+        };
+    }
+    const nowMs = options.nowMs ?? Date.now();
+    const checks = [
+        await checkMemoryInbox(brainPath, nowMs, options.memoryInboxMaxAgeDays ?? DEFAULT_MEMORY_INBOX_MAX_AGE_DAYS),
+        await checkContextPacks(brainPath, nowMs, options.contextPackMaxAgeDays ?? DEFAULT_CONTEXT_PACK_MAX_AGE_DAYS),
+        await checkSessionIndexCoverage(brainPath, options.indexPath ?? INDEX_PATH),
+        await checkEvalFreshness(brainPath, options.evalFreshnessToleranceMs ?? DEFAULT_EVAL_FRESHNESS_TOLERANCE_MS),
+        await checkFinalGates(brainPath),
+    ];
+    if (options.scanMarkdownHygiene !== false)
+        checks.push(await checkMarkdownHygiene(brainPath));
+    return { ok: !checks.some((check) => check.status === 'fail'), brainPath, checks };
+}
+function statusLabel(status) {
+    return status.toUpperCase().padEnd(4);
+}
+export function formatBrainReviewReport(report) {
+    const lines = ['Sanook brain review', `vault: ${report.brainPath ?? '(not configured)'}`];
+    const warnCount = report.checks.filter((check) => check.status === 'warn').length;
+    const failCount = report.checks.filter((check) => check.status === 'fail').length;
+    lines.push(`summary: ${report.checks.length} check(s), ${warnCount} warning(s), ${failCount} failure(s)`);
+    for (const check of report.checks) {
+        lines.push(`[${statusLabel(check.status)}] ${check.id} — ${check.message}`);
+        if (check.path)
+            lines.push(`       ${check.path}`);
+        for (const finding of check.findings ?? []) {
+            lines.push(`       - ${finding.message}`);
+            if (finding.path && finding.path !== check.path)
+                lines.push(`         ${finding.path}`);
+            for (const detail of finding.details ?? [])
+                lines.push(`         · ${detail}`);
+        }
+    }
+    return lines.join('\n');
+}