A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
feat: tidy-fix — deterministic --fix consumer for detector findings (#140)
Brenno Ferrarid19689779b9b
diff --git a/.claude/commands/om-tidy.md b/.claude/commands/om-tidy.mdindex b210405..96a25ec 100644--- a/.claude/commands/om-tidy.md+++ b/.claude/commands/om-tidy.md@@ -32,6 +32,10 @@ Work through the current hygiene flags in order:Write `thinking/YYYY-MM-DD-tidy-report.md`: actions taken (moves, splits, links), flags cleared, judgment calls deferred, open loops listed. Keep it compact — the report is a receipt, not an essay. Delete it once its findings are resolved (thinking/ is a scratchpad by contract).+## Headless subset++`node --experimental-strip-types .claude/scripts/tidy-fix.ts [--apply]` runs the DETERMINISTIC subset from cron with no agent: archives completed work, migrates misplaced memory files (copy → regenerate index → verify → remove), and refuses every judgment class with a pointer back here. Dry-run by default.+## Related- `/om-weekly` § hygiene sweep — the scheduled home of this passdiff --git a/.claude/scripts/generate-memory-index.ts b/.claude/scripts/generate-memory-index.tsindex ba30f7c..4772158 100644--- a/.claude/scripts/generate-memory-index.ts+++ b/.claude/scripts/generate-memory-index.ts@@ -20,18 +20,21 @@ import {} from "./lib/session-start.ts";import { generateMemoryIndex, type BrainNote } from "./lib/memory-index.ts";-function main(): void {- const root = process.env["CLAUDE_PROJECT_DIR"] || process.cwd();+/**+ * Collect brain/ notes (name + description) for index generation. Exported+ * so the tidy-fix consumer regenerates the index from the same walk.+ * Returns null when brain/ is missing.+ */+export function collectBrainNotes(root: string): BrainNote[] | null {let entries: string[] = [];try {entries = readdirSync(join(root, "brain")).filter((n) =>isMarkdownFilename(n),);} catch {- process.stderr.write("brain/ not found — run from the vault root.\n");- process.exit(1);+ return null;}- const notes: BrainNote[] = entries.map((f) => {+ return entries.map((f) => {let description: string | null = null;try {description = extractFrontmatterField(@@ -43,6 +46,15 @@ function main(): void {}return { name: f.replace(/\.md$/i, ""), description };});+}++function main(): void {+ const root = process.env["CLAUDE_PROJECT_DIR"] || process.cwd();+ const notes = collectBrainNotes(root);+ if (notes === null) {+ process.stderr.write("brain/ not found — run from the vault root.\n");+ process.exit(1);+ }process.stdout.write(generateMemoryIndex(notes));}diff --git a/.claude/scripts/tests/tidy-fix.test.ts b/.claude/scripts/tests/tidy-fix.test.tsnew file mode 100644index 0000000..15fce52--- /dev/null+++ b/.claude/scripts/tests/tidy-fix.test.ts@@ -0,0 +1,146 @@+/**+ * Subprocess tests for tidy-fix.ts (#139) — the deterministic --fix+ * consumer. Fixture vault in a tmpdir (non-git, so the plain-rename+ * fallback path is exercised); memory dir routed via TIDY_FIX_MEMORY_DIR.+ * Asserts both tiers: acts on the deterministic classes, refuses the+ * judgment classes, dry-run touches nothing, second run fixes nothing.+ */++import { test, describe, before, after } from "node:test";+import assert from "node:assert/strict";+import { spawnSync } from "node:child_process";+import {+ existsSync,+ mkdirSync,+ mkdtempSync,+ readFileSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { join, dirname, resolve } from "node:path";+import { tmpdir } from "node:os";+import { fileURLToPath } from "node:url";++const SCRIPT = resolve(+ dirname(fileURLToPath(import.meta.url)),+ "../tidy-fix.ts",+);++let ROOT = "";+let MEMDIR = "";++function run(args: string[]): { stdout: string; code: number } {+ const r = spawnSync(+ process.execPath,+ ["--disable-warning=ExperimentalWarning", "--experimental-strip-types", SCRIPT, ...args],+ {+ encoding: "utf-8",+ env: {+ ...process.env,+ CLAUDE_PROJECT_DIR: ROOT,+ TIDY_FIX_MEMORY_DIR: MEMDIR,+ },+ },+ );+ return { stdout: r.stdout ?? "", code: r.status ?? -1 };+}++function note(rel: string, status: string, date: string): void {+ const full = join(ROOT, rel);+ mkdirSync(dirname(full), { recursive: true });+ writeFileSync(+ full,+ `---\nstatus: ${status}\ndate: ${date}\ndescription: "d"\ntags: [x]\n---\n[[Link]]\n`,+ );+}++before(() => {+ ROOT = mkdtempSync(join(tmpdir(), "tidy-fix-test-"));+ MEMDIR = mkdtempSync(join(tmpdir(), "tidy-fix-mem-"));+ note("work/active/Done Solo.md", "completed", "2025-06-01");+ note("work/active/Live One.md", "active", "2026-07-01");+ note("work/active/Mixed Topic/Done.md", "completed", "2026-01-01");+ note("work/active/Mixed Topic/Live.md", "active", "2026-01-01");+ note("work/active/Full Topic/A.md", "completed", "2024-03-01");+ note("work/active/Full Topic/B.md", "completed", "2024-04-01");+ note("work/active/Split Years/A.md", "completed", "2023-11-01");+ note("work/active/Split Years/B.md", "completed", "2024-02-01");+ mkdirSync(join(ROOT, "brain"), { recursive: true });+ writeFileSync(+ join(ROOT, "brain/Patterns.md"),+ '---\ndescription: "patterns"\n---\n# P\n',+ );+ writeFileSync(join(ROOT, "brain/Collide.md"), "# existing brain note\n");+ writeFileSync(join(MEMDIR, "MEMORY.md"), "old index\n");+ writeFileSync(join(MEMDIR, "stray-note.md"), "# stray durable knowledge\n");+ writeFileSync(join(MEMDIR, "Collide.md"), "# different content\n");+});++after(() => {+ rmSync(ROOT, { recursive: true, force: true });+ rmSync(MEMDIR, { recursive: true, force: true });+});++describe("tidy-fix", () => {+ test("dry-run lists both tiers and touches nothing", () => {+ const { stdout, code } = run([]);+ assert.equal(code, 0);+ assert.match(stdout, /DRY-RUN/);+ assert.match(stdout, /Would fix:/);+ assert.match(stdout, /Done Solo\.md → work\/archive\/2025\/Done Solo\.md/);+ assert.match(stdout, /Full Topic\/ → work\/archive\/2024\/Full Topic\/ \(whole cluster\)/);+ assert.match(stdout, /Mixed Topic\/ — mixed cluster/);+ assert.match(stdout, /Split Years\/ — completed notes span years \(2023, 2024\)/);+ assert.match(stdout, /stray-note\.md → brain\/stray-note\.md/);+ assert.match(stdout, /memory\/Collide\.md — brain\/Collide\.md already exists/);+ // Nothing moved.+ assert.ok(existsSync(join(ROOT, "work/active/Done Solo.md")));+ assert.ok(existsSync(join(MEMDIR, "stray-note.md")));+ assert.ok(!existsSync(join(ROOT, "brain/stray-note.md")));+ });++ test("apply acts on the deterministic tier only", () => {+ const { stdout, code } = run(["--apply"]);+ assert.equal(code, 0);+ assert.match(stdout, /APPLIED/);+ // Solo completed → year from frontmatter.+ assert.ok(existsSync(join(ROOT, "work/archive/2025/Done Solo.md")));+ assert.ok(!existsSync(join(ROOT, "work/active/Done Solo.md")));+ // Fully-completed cluster moves whole.+ assert.ok(existsSync(join(ROOT, "work/archive/2024/Full Topic/A.md")));+ assert.ok(!existsSync(join(ROOT, "work/active/Full Topic")));+ // Multi-year cluster refused — untouched.+ assert.ok(existsSync(join(ROOT, "work/active/Split Years/A.md")));+ // Mixed cluster refused — untouched.+ assert.ok(existsSync(join(ROOT, "work/active/Mixed Topic/Done.md")));+ assert.ok(existsSync(join(ROOT, "work/active/Mixed Topic/Live.md")));+ // Active note untouched.+ assert.ok(existsSync(join(ROOT, "work/active/Live One.md")));+ // Memory stray: copied, verified, removed; index regenerated.+ assert.equal(+ readFileSync(join(ROOT, "brain/stray-note.md"), "utf-8"),+ "# stray durable knowledge\n",+ );+ assert.ok(!existsSync(join(MEMDIR, "stray-note.md")));+ const index = readFileSync(join(MEMDIR, "MEMORY.md"), "utf-8");+ assert.match(index, /\[\[brain\/stray-note\]\]/);+ assert.match(index, /\[\[brain\/Patterns\]\] — patterns/);+ // Collision refused: stray stays, brain note unchanged.+ assert.ok(existsSync(join(MEMDIR, "Collide.md")));+ assert.equal(+ readFileSync(join(ROOT, "brain/Collide.md"), "utf-8"),+ "# existing brain note\n",+ );+ });++ test("second apply run fixes nothing (idempotent); refusals persist", () => {+ const { stdout, code } = run(["--apply"]);+ assert.equal(code, 0);+ assert.doesNotMatch(stdout, /^Fixed:$/m);+ assert.doesNotMatch(stdout, /Done Solo/);+ assert.doesNotMatch(stdout, /stray-note/);+ // The judgment findings are still surfaced.+ assert.match(stdout, /Mixed Topic\/ — mixed cluster/);+ assert.match(stdout, /Refused \(judgment — run \/om-tidy\)/);+ });+});diff --git a/.claude/scripts/tidy-fix.ts b/.claude/scripts/tidy-fix.tsnew file mode 100644index 0000000..4c3b0da--- /dev/null+++ b/.claude/scripts/tidy-fix.ts@@ -0,0 +1,326 @@+#!/usr/bin/env node+/**+ * tidy-fix — the deterministic --fix consumer (#139).+ *+ * Re-runs the same pure detector libs the hooks use and ACTS on the two+ * finding classes that involve zero judgment; everything else is printed+ * as a refusal pointing at /om-tidy (agent tier). The refusal list is what+ * makes this safe to run from cron.+ *+ * ACTS on:+ * - completed-in-active → git mv to work/archive/YYYY/ (year from the+ * note's `date` frontmatter; current year when absent). A note inside+ * an active/<Topic>/ cluster moves only when EVERY note in the+ * cluster is completed — mixed clusters are judgment, refused.+ * - misplaced-memory → the #81 review sequence, verbatim: copy the+ * stray file into brain/, regenerate the MEMORY.md index, VERIFY the+ * copy byte-matches, and only then remove the stray.+ *+ * REFUSES (by design, not omission):+ * - topic clusters (token overlap is blind — shared context is agent+ * judgment), oversized-note splits, open loops, inbox pressure,+ * mixed-completion clusters, brain/ name collisions.+ *+ * Never edits prose indexes (work/Index.md rows are reported, not moved+ * — deterministic edits to judgment-shaped files is how fixers overreach).+ *+ * Dry-run by default; pass --apply to act. Idempotent: fixed findings stop+ * being findings, so a second run reports nothing.+ *+ * Usage:+ * node --experimental-strip-types .claude/scripts/tidy-fix.ts [--apply]+ *+ * TIDY_FIX_MEMORY_DIR overrides the auto-memory dir (tests); otherwise it+ * is derived from Claude Code's project-slug convention on POSIX paths and+ * skipped (with a note) when it can't be derived or doesn't exist.+ */++import { spawnSync } from "node:child_process";+import {+ existsSync,+ mkdirSync,+ readdirSync,+ readFileSync,+ renameSync,+ rmSync,+ writeFileSync,+} from "node:fs";+import { homedir } from "node:os";+import { basename, dirname, join } from "node:path";+import { isMainModule } from "./lib/main-guard.ts";+import {+ extractFrontmatterField,+ isMarkdownFilename,+ parseInfraRootFilenames,+} from "./lib/session-start.ts";+import {+ parseOpenLoopConfig,+ scanActiveHygiene,+ walkMarkdown,+} from "./lib/active-hygiene.ts";+import { generateMemoryIndex } from "./lib/memory-index.ts";+import { collectBrainNotes } from "./generate-memory-index.ts";++const ACTIVE_REL = "work/active";++type Report = {+ readonly fixed: string[];+ readonly refused: string[];+ readonly notes: string[];+};++/** Claude Code's project slug: POSIX path with separators dashed. */+function deriveMemoryDir(vaultRoot: string): string | null {+ const override = process.env["TIDY_FIX_MEMORY_DIR"];+ if (override) return override;+ const posix = vaultRoot.replaceAll("\\", "/").replace(/\/+$/, "");+ if (!posix.startsWith("/")) return null; // Windows slug convention unknown+ const slug = posix.replaceAll("/", "-");+ return join(homedir(), ".claude", "projects", slug, "memory");+}++/** git mv with a plain-rename fallback (still zero-loss; noted in output). */+function moveTracked(+ vaultRoot: string,+ relSrc: string,+ relDest: string,+ notes: string[],+): boolean {+ mkdirSync(join(vaultRoot, dirname(relDest)), { recursive: true });+ const git = spawnSync("git", ["mv", relSrc, relDest], {+ cwd: vaultRoot,+ encoding: "utf-8",+ });+ if (git.status === 0) return true;+ try {+ renameSync(join(vaultRoot, relSrc), join(vaultRoot, relDest));+ notes.push(` (plain rename for ${relSrc} — git mv unavailable here)`);+ return true;+ } catch {+ notes.push(` could not move ${relSrc} — left in place`);+ return false;+ }+}++function archiveYear(vaultRoot: string, rel: string): string {+ try {+ const date = extractFrontmatterField(+ readFileSync(join(vaultRoot, rel), "utf-8"),+ "date",+ );+ const m = date?.match(/^(\d{4})/);+ if (m) return m[1] as string;+ } catch {+ /* fall through */+ }+ return String(new Date().getFullYear());+}++function fixCompletedInActive(+ vaultRoot: string,+ completed: readonly string[],+ apply: boolean,+ report: Report,+): void {+ // Group findings: loose files move alone; a file inside active/<Topic>/+ // moves only when the WHOLE cluster is completed.+ const completedSet = new Set(completed);+ const handledClusters = new Set<string>();++ for (const rel of completed) {+ const inside = rel.slice(`${ACTIVE_REL}/`.length);+ const slash = inside.indexOf("/");+ if (slash === -1) {+ const year = archiveYear(vaultRoot, rel);+ const dest = `work/archive/${year}/${inside}`;+ report.fixed.push(`${rel} → ${dest}`);+ if (apply) moveTracked(vaultRoot, rel, dest, report.notes);+ report.notes.push(` move its row in work/Index.md (${basename(rel)})`);+ continue;+ }+ const topic = inside.slice(0, slash);+ const clusterRel = `${ACTIVE_REL}/${topic}`;+ if (handledClusters.has(clusterRel)) continue;+ handledClusters.add(clusterRel);+ // Sorted: walkMarkdown returns filesystem order, which differs across+ // machines — output must be deterministic.+ const members = walkMarkdown(vaultRoot, clusterRel).sort();+ const allDone = members.every((m) => completedSet.has(m));+ if (!allDone) {+ report.refused.push(+ `${clusterRel}/ — mixed cluster (some notes still active); archiving a partial workstream is judgment`,+ );+ continue;+ }+ // The archive year is deterministic only when every member agrees;+ // a cluster spanning years has no correct single bucket — judgment.+ const years = new Set(members.map((m) => archiveYear(vaultRoot, m)));+ if (years.size > 1) {+ report.refused.push(+ `${clusterRel}/ — completed notes span years (${[...years].sort().join(", ")}); the archive-year choice is judgment`,+ );+ continue;+ }+ const year = [...years][0] as string;+ const dest = `work/archive/${year}/${topic}`;+ report.fixed.push(`${clusterRel}/ → ${dest}/ (whole cluster)`);+ if (apply) moveTracked(vaultRoot, clusterRel, dest, report.notes);+ report.notes.push(` move its row in work/Index.md (${topic})`);+ }+}++function fixMisplacedMemory(+ vaultRoot: string,+ apply: boolean,+ report: Report,+): void {+ const memDir = deriveMemoryDir(vaultRoot);+ if (memDir === null) {+ report.notes.push(+ "memory dir not derivable on this platform — misplaced-memory scan skipped",+ );+ return;+ }+ let entries: string[];+ try {+ entries = readdirSync(memDir).filter(+ (n) => isMarkdownFilename(n) && n !== "MEMORY.md",+ );+ } catch {+ return; // no memory dir on this machine — nothing to fix+ }+ if (entries.length === 0) return;++ let migrated = 0;+ for (const stray of entries) {+ const target = join(vaultRoot, "brain", stray);+ if (existsSync(target)) {+ report.refused.push(+ `memory/${stray} — brain/${stray} already exists; merging content is judgment`,+ );+ continue;+ }+ report.fixed.push(`memory/${stray} → brain/${stray} (copy, verify, remove)`);+ report.notes.push(+ ` review brain/${stray} before committing — auto-memory content can be personal, and brain/ is repo-tracked`,+ );+ if (!apply) continue;+ const content = readFileSync(join(memDir, stray), "utf-8");+ mkdirSync(join(vaultRoot, "brain"), { recursive: true });+ writeFileSync(target, content);+ const copied = readFileSync(target, "utf-8");+ if (copied !== content) {+ report.notes.push(+ ` VERIFY FAILED for ${stray} — stray left in place, copy left for inspection`,+ );+ continue;+ }+ migrated++;+ }+ if (apply && migrated > 0) {+ // Regenerate the index from brain/ (now including the migrated notes),+ // THEN remove the verified strays — hegu-1's sequence from #81.+ // Removal is GATED on successful regeneration: if the index step+ // fails, the strays stay (copies remain in brain/ for inspection).+ let indexOk = false;+ try {+ const notes = collectBrainNotes(vaultRoot);+ if (notes !== null) {+ writeFileSync(join(memDir, "MEMORY.md"), generateMemoryIndex(notes));+ report.notes.push(" MEMORY.md regenerated");+ indexOk = true;+ } else {+ report.notes.push(+ " index NOT regenerated (brain/ unreadable) — strays left in place",+ );+ }+ } catch {+ report.notes.push(+ " index regeneration failed — strays left in place",+ );+ }+ if (!indexOk) return;+ for (const stray of entries) {+ const target = join(vaultRoot, "brain", stray);+ if (!existsSync(target)) continue; // refused or verify-failed+ try {+ if (+ readFileSync(target, "utf-8") ===+ readFileSync(join(memDir, stray), "utf-8")+ ) {+ rmSync(join(memDir, stray));+ }+ } catch {+ report.notes.push(+ ` could not remove memory/${stray} — copy in brain/ is verified; remove by hand`,+ );+ }+ }+ }+}++function main(): void {+ const apply = process.argv.includes("--apply");+ const vaultRoot = (process.env["CLAUDE_PROJECT_DIR"] || process.cwd())+ .replaceAll("\\", "/")+ .replace(/\/+$/, "");++ let manifestJson: string | null = null;+ try {+ manifestJson = readFileSync(join(vaultRoot, "vault-manifest.json"), "utf-8");+ } catch {+ /* defaults */+ }+ const scan = scanActiveHygiene(+ vaultRoot,+ Date.now(),+ parseOpenLoopConfig(manifestJson),+ parseInfraRootFilenames(manifestJson),+ );++ const report: Report = { fixed: [], refused: [], notes: [] };++ fixCompletedInActive(vaultRoot, scan.completedInActive, apply, report);+ fixMisplacedMemory(vaultRoot, apply, report);++ // Judgment tier — refuse loudly so cron output still surfaces the state.+ for (const c of scan.ungroupedClusters) {+ report.refused.push(+ `cluster "${c.token}" (${c.files.length} notes) — shared context is judgment`,+ );+ }+ for (const o of scan.oversizedNotes) {+ report.refused.push(`${o.path} (${o.sizeKb}KB) — splitting is judgment`);+ }+ for (const l of scan.openLoops) {+ report.refused.push(+ `${l.path} (${l.ageDays}d, ${l.openItems} open) — chase/close/park is the user's call`,+ );+ }+ if (scan.inboxPressure !== null) {+ report.refused.push(+ `${scan.inboxPressure.count} raw export(s) in work/meetings/ — run /om-intake`,+ );+ }++ const mode = apply ? "APPLIED" : "DRY-RUN (pass --apply to act)";+ console.log(`tidy-fix — ${mode}`);+ if (report.fixed.length === 0 && report.refused.length === 0) {+ console.log("nothing to do — vault is clean.");+ return;+ }+ if (report.fixed.length > 0) {+ console.log(apply ? "\nFixed:" : "\nWould fix:");+ for (const f of report.fixed) console.log(` ${f}`);+ }+ if (report.refused.length > 0) {+ console.log("\nRefused (judgment — run /om-tidy):");+ for (const r of report.refused) console.log(` ${r}`);+ }+ if (report.notes.length > 0) {+ console.log("\nNotes:");+ for (const n of report.notes) console.log(`${n}`);+ }+}++if (isMainModule(import.meta.url)) main();