Skip to content

Cortex: KnowledgeLint and the SessionEnd conformance check never resolve related: targets, so dead and ambiguous links report as fully conformant #2828

Open

Description

@Luo0oo

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/ and Companies/), 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:

  1. KnowledgeLint.ts: build the index once over all directories, even when --dir narrows the report (otherwise a link from an Idea to a Person reads as dead), add resolveRelated(parsed, index) beside validate() for each note, and report dangling_edges, dangling_targets (distinct slugs), ambiguous_edges and slug_collisions in --json and the text summary.
  2. KnowledgeConformance.ts: the same index and the same call, so dead and ambiguous links flow into the existing doc.integrity.knowledge_conformance finding 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions