A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
feat: Write-Correctness Laws, agent-docs sync guard, index-first wrap-up, failing manifest-check (#132)
Brenno Ferrari6357a1cbcaed
diff --git a/.claude/commands/om-wrap-up.md b/.claude/commands/om-wrap-up.mdindex aba261b..6c5ef8f 100644--- a/.claude/commands/om-wrap-up.md+++ b/.claude/commands/om-wrap-up.md@@ -55,7 +55,7 @@ For each note created or modified this session:### 6. Ways of Working Review-Check if this session revealed:+**Index-first**: read each brain note's headline/one-liner structure, then open ONLY the topics this session actually touched — same knowledge transfer, a fraction of the tokens. Check if this session revealed:- A new pattern that should be in `brain/Patterns.md`?- A new gotcha that should be in `brain/Gotchas.md`?- A workflow improvement for `brain/Skills.md`?diff --git a/.claude/scripts/tests/agent-docs-sync.test.ts b/.claude/scripts/tests/agent-docs-sync.test.tsnew file mode 100644index 0000000..6e326fb--- /dev/null+++ b/.claude/scripts/tests/agent-docs-sync.test.ts@@ -0,0 +1,29 @@+/**+ * Duplication-guard (#115): AGENTS.md and GEMINI.md are the same pointer+ * doc by design — two filenames because two agent ecosystems look for+ * them, one content because they say the same thing. When duplication IS+ * the design, guard it with a test so the copies can't drift silently.+ * (The pattern matters more than the instance: apply it wherever the same+ * instruction text must exist in two places that can't reference each+ * other.)+ */++import { test, describe } from "node:test";+import assert from "node:assert/strict";+import { readFileSync } from "node:fs";+import { dirname, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");++describe("agent docs sync", () => {+ test("AGENTS.md and GEMINI.md are byte-identical", () => {+ const agents = readFileSync(resolve(repoRoot, "AGENTS.md"), "utf-8");+ const gemini = readFileSync(resolve(repoRoot, "GEMINI.md"), "utf-8");+ assert.equal(+ agents,+ gemini,+ "AGENTS.md and GEMINI.md drifted — they are the same pointer doc by design; edit both or neither",+ );+ });+});diff --git a/.github/scripts/manifest-check.ts b/.github/scripts/manifest-check.tsindex 665d877..3223b10 100644--- a/.github/scripts/manifest-check.ts+++ b/.github/scripts/manifest-check.ts@@ -3,8 +3,8 @@* PR-time advisory: verify that every tracked template-infrastructure file* is covered by a glob in vault-manifest.json's `infrastructure` array.*- * Emits GitHub workflow `::warning::` annotations for uncovered files. Does- * not fail the job — this is an informational nudge to keep the manifest in+ * Emits GitHub workflow `::error::` annotations for uncovered files and+ * FAILS the job (#51) — manifest drift ships broken upgrades, so the nudge* sync when new template files land.*/@@ -156,7 +156,7 @@ function main(): void {if (missing.length === 0) return;console.log(- "::warning::The following files are not covered by vault-manifest.json infrastructure globs:",+ "::error::The following files are not covered by vault-manifest.json infrastructure globs:",);for (const f of missing) console.log(` - ${f}`);console.log("");@@ -166,6 +166,7 @@ function main(): void {console.log("Also consider adding a version_fingerprints entry if this is a new version-defining file.",);+ process.exitCode = 1;}if (isMainModule(import.meta.url)) main();diff --git a/CLAUDE.md b/CLAUDE.mdindex e2b1525..d985038 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -16,7 +16,7 @@ This vault has [obsidian-skills](https://github.com/kepano/obsidian-skills) inst2. **`qmd --index <name> query|search|vsearch|get|multi-get`** — CLI fallback for one-off shell checks or when the MCP server is unavailable. Always pass `--index <name>` where `<name>` is the `qmd_index` field from `vault-manifest.json` so the SQLite store stays isolated from other vaults on the machine.3. **Grep / Glob / Read** — last resort, only when QMD is not installed at all.- The MCP server (`.mcp.json` → `.claude/scripts/qmd-mcp.mjs`), the CLI, and the SessionStart hook all read the same manifest field, so every surface scopes to the same store. On a fresh clone, run `node --experimental-strip-types scripts/qmd-bootstrap.ts` once to build the index.+ The MCP server (`.mcp.json` → `.claude/scripts/qmd-mcp.mjs`), the CLI, and the SessionStart hook all read the same manifest field, so every surface scopes to the same store. On a fresh clone, run `node --experimental-strip-types scripts/qmd-bootstrap.ts` once to build the index. Note: the MCP connect-time banner can read "0 documents" when the server registers before the SessionStart reindex finishes — a stale snapshot, not the dead-search state the self-heal guards; don't diagnose it.### Custom Slash Commands@@ -343,6 +343,17 @@ Five lifecycle hooks in `.claude/settings.json`:| PreCompact | Before context compaction | Backs up session transcript to `thinking/session-logs/` || Stop | End of every session | Lightweight checklist reminder + concrete vault-hygiene drift findings (same scan as SessionStart). For thorough review, use `/om-wrap-up` instead. |+## Write-Correctness Laws++Each law exists because its absence caused real correction work in vaults running this template. Violating them re-creates documented failures.++1. **Single-source status.** A project's volatile status (version, counts, released/blocked, dates) lives in exactly ONE place — its note's frontmatter + top status line. Every other note **links** to it and never restates it. *Why: one wrong status statement hardened into ~8 notes downstream and had to be swept out.*+2. **Correction-sweep protocol.** When a fact is corrected, grep the vault for every restatement and fix them all in the same pass. A correction callout on top of a note whose body still says the wrong thing is NOT a correction — future sessions re-absorb the stain from the body.+3. **Mark inference.** Anything not verified against source (code, repo, primary doc, the person) carries an explicit `(TBC)` / `(unverified)` / `(inferred)` marker. Never state inference bare.+4. **Date-stamp volatile facts.** Counts, versions, org structure, tool maturity: write "as of YYYY-MM-DD" so staleness is self-evident instead of silent.+5. **Attribution vs. creation dates may differ** (a `quarter:` field vs. the `date:` field's quarter) — that's legitimate, not a bug to "fix".+6. **No counts in instruction files.** Hardcoded counts ("11 slash commands") in CLAUDE.md/README rot silently — describe, don't count.+## Rules- **For "what's most recent," use `bases/Recently Touched.base` (real modified time), never filename dates** — a creation-date prefix on a continuously-edited note inverts the recency signal.