Repository navigation
Description
What. validate() in LIFEOS/TOOLS/KnowledgeSchema.ts checks each note on its own: the shape of its related: block and the type of each link, but not whether the slug a link points at exists. Nothing else checks it either. KnowledgeLint.ts and hooks/handlers/KnowledgeConformance.ts (the SessionEnd check run through DocIntegrity) both call only validate(). So two kinds of broken link go unreported:
- Dead: a link to a slug no note carries (a typo, a renamed note, a note that was merged away).
- Ambiguous: a link to a slug that two directories both carry (the same name in
People/andCompanies/), so the link has no single target.
Repro. Five synthetic notes under a temporary HOME (HOME=$(mktemp -d), notes in $HOME/.claude/LIFEOS/MEMORY/KNOWLEDGE/):
| Note | related: |
|---|---|
Ideas/a.md |
b (exists) and ghost (no such note) |
Ideas/b.md |
none |
People/twin.md, Companies/twin.md |
none |
Ideas/c.md |
twin (two notes carry it) |
$ HOME=$TMP bun LIFEOS/TOOLS/KnowledgeLint.ts --json
{ "total": 5, "fully_conformant": 5, "envelope_conformant": 5, "top_problems": [] }
Both broken links pass. A knowledge graph whose lint cannot see dead edges drifts quietly: every rename or merge leaves dangling links behind, and the reader of a note gets no sign that a cited note is missing.
Suggested fix. An archive-wide target check kept outside validate(). validate() stays per-note and pure, which matters because MigrateKnowledge.ts reads its leftover violations after a rewrite: a dead link is something the migrator cannot repair, so putting it inside validate() would make that signal permanently non-empty. The caller builds one index over every archive directory and passes it to a pure per-note checker.
In KnowledgeSchema.ts:
/**
* Build a slug -> dirs index over note paths. The value lists EVERY parent-dir
* basename holding a note with that slug, so a cross-dir collision (the same
* slug in People and Companies) shows as a 2-entry list instead of being
* flattened into "exists". Callers pass ALL archive dirs, never a filtered
* subset, or a cross-dir link false-fires as unresolved.
*/
export function buildSlugIndex(paths: readonly string[]): Map<string, string[]> {
const index = new Map<string, string[]>();
for (const p of paths) {
const slug = slugFromPath(p);
const parts = p.split("/");
const dir = parts.length >= 2 ? parts[parts.length - 2] : "";
const dirs = index.get(slug) ?? [];
if (!dirs.includes(dir)) dirs.push(dir);
index.set(slug, dirs);
}
return index;
}
/** Matches `slug: x` in block and inline form; `\b` keeps `source_slug:` from matching. */
const RELATED_SLUG_RE = /\bslug:\s*["']?([A-Za-z0-9._-]+)["']?/g;
/**
* Resolve every `related:` target of a note against `known` (slug -> dirs).
* Two classes, both on key `related`, one violation per edge:
* - `target "<slug>" does not resolve` - no note anywhere has that slug
* - `target "<slug>" is ambiguous (<dirs>)` - 2+ dirs hold a note with that slug
* The classes stay separate because their repairs differ.
*/
export function resolveRelated(
parsed: Pick<ParsedNote, "fields">,
known: ReadonlyMap<string, readonly string[]>,
): Violation[] {
const v: Violation[] = [];
const rel = parsed.fields.find((f) => f.key === "related");
if (!rel) return v;
for (const m of rel.raw.matchAll(RELATED_SLUG_RE)) {
const slug = m[1];
const dirs = known.get(slug);
if (!dirs || dirs.length === 0) {
v.push({ key: "related", problem: `target "${slug}" does not resolve` });
} else if (dirs.length >= 2) {
v.push({ key: "related", problem: `target "${slug}" is ambiguous (${dirs.join(", ")})` });
}
}
return v;
}The two callers:
KnowledgeLint.ts: build the index once over all directories, even when--dirnarrows the report (otherwise a link from an Idea to a Person reads as dead), addresolveRelated(parsed, index)besidevalidate()for each note, and reportdangling_edges,dangling_targets(distinct slugs),ambiguous_edgesandslug_collisionsin--jsonand the text summary.KnowledgeConformance.ts: the same index and the same call, so dead and ambiguous links flow into the existingdoc.integrity.knowledge_conformancefinding set with its shape unchanged. This is the only one of the two that runs without anyone typing a command.
Tests. A self-test that runs the real lint against a fixture archive under a temporary HOME, asserting both directions: a planted dead link gives dangling_edges === 1 and removing it gives 0; a planted two-directory slug gives ambiguous_edges === 1 and slug_collisions === 1, and removing one twin gives 0. Asserting that the fixture really was scanned (total equals the fixture's note count) keeps the test from passing against an empty or wrong directory.
One design note. The finding text is read by its callers: the lint counts edges by the substrings does not resolve and is ambiguous, and conformance findings are keyed by the full message. If upstream takes this, it is worth either exporting the two classes as constants or pinning the strings with a test, so a later rewording cannot silently zero the counts.
Happy to open this as a PR if that is easier to review.
Activity