A self-organizing Obsidian vault that gives AI coding agents persistent memory.
TypeScript ai-agentsclaude-codecodex-cligemini-cliknowledge-managementobsidianobsidian-vaultpersistent-memorysecond-braintemplate
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.mdindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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);+ }+ });+});