Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

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.md
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index e2b1525..d985038 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ This vault has [obsidian-skills](https://github.com/kepano/obsidian-skills) inst
2. **`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.