Skip to content

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

feat: gate every anchored promoted marker on resolving, and retarget markers on a split (#311)

Brenno Ferrari44aa3e8a8ffc
diff --git a/.claude/commands/om-tidy.md b/.claude/commands/om-tidy.md
index 335221e..24eec6c 100644
--- a/.claude/commands/om-tidy.md
+++ b/.claude/commands/om-tidy.md
@@ -18,7 +18,7 @@ Work through the current hygiene flags in order:
1. **Completed-not-archived** — `git mv` from `work/active/` to `work/archive/YYYY/`; clusters keep their folder (mirror the grouping); update `work/Index.md`. Same semantics as `/om-project-archive` — use it for anything with ceremony.
2. **Ungrouped clusters** — when the loose notes genuinely share context (judge, don't trust token overlap): create `work/active/<Topic>/`, `git mv` the members in.
-3. **Oversized notes (25KB+)** — SPLIT, never trim: move whole sections verbatim into domain notes, event-log satellites, or an archive note; leave a one-liner index behind in the original; retarget links that pointed at the moved sections. `*Archive*` names are exempt by design. A split is complete only when the new notes are wired into the graph — search each new note's concepts (QMD when available) and link what surfaces.
+3. **Oversized notes (25KB+)** — SPLIT, never trim: move whole sections verbatim into domain notes, event-log satellites, or an archive note; leave a one-liner index behind in the original; retarget links that pointed at the moved sections. **Retarget `promoted:` markers too**: they live in `memories/`, not in the note being split, so nothing in view shows them — `grep -rn "promoted:.*<Note name>#" memories/` finds every capture whose promoted block moved, and each must name the block's new note. A split orphans them silently otherwise; `tests/vault-promoted.test.ts` fails until every anchored marker resolves. `*Archive*` names are exempt by design. A split is complete only when the new notes are wired into the graph — search each new note's concepts (QMD when available) and link what surfaces.
4. **Index drift, orphans, broken links** — new notes must be linked from at least one note; fix wikilinks broken by any moves this pass made; update `work/Index.md` / `org/People & Context.md` / `perf/Brag Doc.md` as touched.
5. **Semantic-linking pass** — for notes created or split this pass, `qmd query` their core concepts (index name from `vault-manifest.json`) and add the links the graph is missing.
6. **Memory-inbox promotion (`memories/YYYY/MM/`)** — durable captures get copied into the right `brain/` topic note. **Promotion is ADDITIVE: copy, never move.** `recall` reaches `brain/` only *through* a capture, so deleting one removes the lesson from every repo that cannot read `brain/` at all — which is the whole audience it was written for.
diff --git a/.claude/scripts/lib/promoted-gate.ts b/.claude/scripts/lib/promoted-gate.ts
new file mode 100644
index 0000000..f75a369
--- /dev/null
+++ b/.claude/scripts/lib/promoted-gate.ts
@@ -0,0 +1,115 @@
+/**
+ * The vault-wide check that every anchored `promoted:` marker resolves (#246).
+ *
+ * `resolvePromoted` is careful and well tested on fixtures, but nothing
+ * asserted that a REAL vault's markers resolve, and one routine edit breaks
+ * them silently: splitting a note. A split retargets the wikilinks in view,
+ * while the markers pointing into the note live in `memories/` and are not
+ * in view, so every one of them is orphaned and recall quietly falls back to
+ * the capture as first written. The hygiene report already said so, every
+ * session, and nothing acted on it, because a report can be walked past and
+ * a failing test cannot.
+ *
+ * Resolution is `auditPromotions`, the same path `health` reports from, so
+ * the gate and the report cannot disagree about what "resolves" means. On
+ * top of it the gate requires a block anchor to be DEFINED exactly once in
+ * its note. A definition is `^anchor` not preceded by `#` (a `[[#^anchor]]`
+ * or `[[Note#^anchor]]` is a reference to it, and counting those penalised
+ * exactly the cross-linking a vault wants) and not followed by another
+ * identifier character (`^om-fix` is a prefix of `^om-fix-escape`).
+ *
+ * Unanchored markers are skipped: a bare `promoted: brain/Note` is a
+ * deliberate, reported state, not a defect.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { ExposurePolicy } from "./mcp-exposure.ts";
+import { resolveExposedNote } from "./mcp-exposure.ts";
+import { auditPromotions } from "./memory-promoted.ts";
+import { readMemories } from "./memory-recall.ts";
+import { stripFrontmatter } from "./session-start.ts";
+
+export type PromotedGateResult = {
+ /** Markdown files under the memory root, parsed or not. */
+ readonly files: number;
+ /** Captures the store reader parsed. */
+ readonly captures: number;
+ /** Markers carrying an anchor — the only kind the gate checks. */
+ readonly anchored: number;
+ /** One line per marker that does not resolve, naming the capture. */
+ readonly failures: readonly string[];
+};
+
+function countMarkdown(dir: string): number {
+ let n = 0;
+ let entries: string[];
+ try {
+ entries = readdirSync(dir);
+ } catch {
+ return 0;
+ }
+ for (const name of entries) {
+ const full = join(dir, name);
+ try {
+ if (statSync(full).isDirectory()) n += countMarkdown(full);
+ else if (name.toLowerCase().endsWith(".md")) n++;
+ } catch {
+ /* vanished mid-walk */
+ }
+ }
+ return n;
+}
+
+/** How many times `^anchor` is defined in `body`: not after `#`, ended on a boundary. */
+export function countAnchorDefinitions(body: string, anchor: string): number {
+ const escaped = anchor.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+ return (body.match(new RegExp(`(?<!#)\\^${escaped}(?![\\w-])`, "g")) ?? []).length;
+}
+
+export function checkPromotedMarkers(vaultRoot: string, memoryRoot: string): PromotedGateResult {
+ const files = countMarkdown(join(vaultRoot, memoryRoot));
+ const entries = readMemories(vaultRoot, memoryRoot);
+ const failures: string[] = [];
+
+ // The gate asks whether a marker RESOLVES, not whether the server may serve
+ // it, so every marker's own folder is treated as exposed here.
+ const roots = new Set<string>();
+ for (const e of entries) {
+ const note = e.facets.promoted?.note;
+ const top = note?.split("/")[0];
+ if (top && top !== note) roots.add(top);
+ }
+ const policy: ExposurePolicy = { roots: [...roots], neverExpose: new Set(), source: "manifest", memoryRoot };
+
+ const audit = auditPromotions(
+ vaultRoot,
+ policy,
+ entries.map((e) => ({ path: e.rel, facets: e.facets })),
+ );
+ for (const p of audit.unparsed) failures.push(`${p}: promoted: marker cannot be parsed`);
+ for (const b of audit.broken) {
+ const why = b.status === "stale-anchor" ? "its anchor is not in that note (moved by a split?)" : `the note is ${b.status}`;
+ failures.push(`${b.path}: promoted into ${b.note}, but ${why}`);
+ }
+
+ // A block anchor that resolved may still be defined twice; recall serves
+ // the first, which may not be the block that was promoted.
+ for (const e of entries) {
+ const ref = e.facets.promoted;
+ if (!ref || ref.anchor === null || ref.kind !== "block") continue;
+ const full = resolveExposedNote(vaultRoot, policy, ref.note);
+ if (full === null || !existsSync(full)) continue; // already reported as broken
+ let body = "";
+ try {
+ body = stripFrontmatter(readFileSync(full, "utf8"));
+ } catch {
+ continue;
+ }
+ const defs = countAnchorDefinitions(body, ref.anchor);
+ if (defs > 1) failures.push(`${e.rel}: ^${ref.anchor} is defined ${defs} times in ${ref.note}; recall cannot tell which block is meant`);
+ }
+
+ // `broken` holds anchored markers only; a bare marker counts as named-only.
+ return { files, captures: entries.length, anchored: audit.served + audit.broken.length, failures };
+}
diff --git a/.claude/scripts/tests/vault-promoted.test.ts b/.claude/scripts/tests/vault-promoted.test.ts
new file mode 100644
index 0000000..8725036
--- /dev/null
+++ b/.claude/scripts/tests/vault-promoted.test.ts
@@ -0,0 +1,161 @@
+/**
+ * Promoted-marker GATE (#246): every anchored `promoted:` marker in this
+ * vault's memory store must resolve to exactly one block.
+ *
+ * Splitting a note is the prescribed fix for an oversized one, and it orphans
+ * every marker pointing into the note: the markers live in `memories/`, out of
+ * view of the split. Recall then serves the capture as first written instead
+ * of the corrected block, and nothing errors. A zero gate, in the shape of
+ * `vault-wikilinks.test.ts`, makes that state impossible to walk past.
+ *
+ * The first block runs on the REAL vault. A vault with no captures (the
+ * template) skips it, saying why; a vault whose memory folder holds notes the
+ * reader parsed none of fails rather than passing on an empty walk. The rest
+ * pin the rules on fixtures.
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { parseMemoryRoot } from "../lib/active-hygiene.ts";
+import { checkPromotedMarkers, countAnchorDefinitions } from "../lib/promoted-gate.ts";
+import { rmTemp } from "./_helpers.ts";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");
+
+function manifestJson(): string | null {
+ try {
+ return readFileSync(join(repoRoot, "vault-manifest.json"), "utf8");
+ } catch {
+ return null;
+ }
+}
+
+describe("promoted markers — this vault", () => {
+ const memoryRoot = parseMemoryRoot(manifestJson());
+ const result = checkPromotedMarkers(repoRoot, memoryRoot);
+ const noCaptures = result.files === 0 ? `no captures in ${memoryRoot}/ — nothing to check` : false;
+
+ test("the walk read the store it was given", { skip: noCaptures }, () => {
+ assert.ok(
+ result.captures > 0,
+ `${memoryRoot}/ holds ${result.files} notes and the reader parsed none — a gate on an empty walk proves nothing`,
+ );
+ });
+
+ test("every anchored marker resolves to exactly one block", { skip: noCaptures }, () => {
+ assert.deepEqual(
+ result.failures,
+ [],
+ `${result.failures.length} promoted marker(s) do not resolve. After a split, point each at the block's new note:\n ${result.failures.join("\n ")}`,
+ );
+ });
+});
+
+describe("promoted markers — the rules", () => {
+ function vault(notes: Record<string, string>): string {
+ const dir = mkdtempSync(join(tmpdir(), "promoted-gate-"));
+ for (const [rel, body] of Object.entries(notes)) {
+ mkdirSync(dirname(join(dir, rel)), { recursive: true });
+ writeFileSync(join(dir, rel), body);
+ }
+ return dir;
+ }
+ const capture = (marker: string) => `---\ntitle: A lesson\npromoted: "${marker}"\n---\nThe lesson as first written.\n`;
+
+ test("a marker whose block is in the named note passes", () => {
+ const dir = vault({
+ "memories/2026/09/a.md": capture("brain/Gotchas#^om-a1"),
+ "brain/Gotchas.md": "# Gotchas\n\nThe corrected lesson. ^om-a1\n",
+ });
+ try {
+ const r = checkPromotedMarkers(dir, "memories");
+ assert.deepEqual(r.failures, []);
+ assert.equal(r.anchored, 1);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("after a split moved the block, the marker fails and names the capture", () => {
+ const dir = vault({
+ "memories/2026/09/a.md": capture("brain/Gotchas#^om-a1"),
+ "brain/Gotchas.md": "# Gotchas\n\n- moved to [[Gotchas - Tooling]]\n",
+ "brain/Gotchas - Tooling.md": "# Tooling\n\nThe corrected lesson. ^om-a1\n",
+ });
+ try {
+ const r = checkPromotedMarkers(dir, "memories");
+ assert.equal(r.failures.length, 1);
+ assert.match(r.failures[0]!, /2026\/09\/a\.md: promoted into brain\/Gotchas.* anchor is not in that note/);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("a marker into a note that no longer exists fails", () => {
+ const dir = vault({ "memories/2026/09/a.md": capture("brain/Gone#^om-a1"), "brain/Other.md": "x\n" });
+ try {
+ assert.equal(checkPromotedMarkers(dir, "memories").failures.length, 1);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("an anchor defined twice in its note fails", () => {
+ const dir = vault({
+ "memories/2026/09/a.md": capture("brain/Gotchas#^om-a1"),
+ "brain/Gotchas.md": "# G\n\nFirst. ^om-a1\n\nSecond. ^om-a1\n",
+ });
+ try {
+ const [f] = checkPromotedMarkers(dir, "memories").failures;
+ assert.match(f ?? "", /\^om-a1 is defined 2 times/);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("references to the block, and a longer anchor sharing its prefix, are not definitions", () => {
+ const body = "Block. ^om-fix\n\nSee [[#^om-fix]] and [[Gotchas#^om-fix]].\n\nOther. ^om-fix-escape\n";
+ assert.equal(countAnchorDefinitions(body, "om-fix"), 1);
+ assert.equal(countAnchorDefinitions(body, "om-fix-escape"), 1);
+ });
+
+ test("a bare marker (no anchor) is a reported state, not a failure", () => {
+ const dir = vault({ "memories/2026/09/a.md": capture("brain/Gotchas"), "brain/Gotchas.md": "x\n" });
+ try {
+ const r = checkPromotedMarkers(dir, "memories");
+ assert.deepEqual(r.failures, []);
+ assert.equal(r.anchored, 0);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("an unparseable marker fails, naming the capture", () => {
+ // A control character makes the marker unparseable (parsePromotedMarker
+ // refuses it): the frontmatter says promoted, every consumer sees nothing.
+ const dir = vault({ "memories/2026/09/a.md": "---\ntitle: A\npromoted: \"brain/Gotchas#^om\u0007a1\"\n---\nbody\n", "brain/Gotchas.md": "x\n" });
+ try {
+ const [f] = checkPromotedMarkers(dir, "memories").failures;
+ assert.match(f ?? "", /a\.md: promoted: marker cannot be parsed/);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+
+ test("files and captures are counted apart, so an empty walk over a full folder is visible", () => {
+ const dir = vault({ "memories/2026/09/a.md": capture("brain/Gotchas#^om-a1"), "brain/Gotchas.md": "x ^om-a1\n" });
+ try {
+ const r = checkPromotedMarkers(dir, "memories");
+ assert.equal(r.files, 1);
+ assert.equal(r.captures, 1);
+ assert.equal(checkPromotedMarkers(dir, "elsewhere").files, 0);
+ } finally {
+ rmTemp(dir);
+ }
+ });
+});