feat(context): frontmatter-driven keyword routing + drift-proof index

Make context discovery deterministic instead of agent-judgment-dependent:

- Add `keywords` (required) and `related` (optional cross-links) to the
  context-file frontmatter contract (vc-context-discovery SKILL.md + seeds).
- discover-context.mjs: `--match` ranks docs by keyword overlap and follows
  `related` siblings; `--emit-routing` regenerates the Root-Entry-Points and
  Context-Groups tables from frontmatter (between GENERATED:routing markers),
  killing router drift; `--check-routing` fails when the block is stale.
- validate-context-discovery.mjs: enforce non-empty keywords, resolve every
  `related` slug (no dangling links), and fail on a stale generated block.
- Wire the lifecycle: context-maintenance.md and generate-context.md now edit
  frontmatter + --emit-routing rather than hand-editing the router tables.

Task-Routing table stays hand-authored (editorial task-type -> file mapping).
Bare-kit mode unaffected; kit validators still pass clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: withkynam

.claude/skills/vc-audit-context/scripts/validate-context-discovery.mjs

@@ -188,6 +188,54 @@ if (!bareKitMode) {
     }
   }
 
+  // --- frontmatter routing contract: keyword coverage + related-link integrity ---
+  // Build a slug registry (context:{slug}) across all context docs first.
+  const contextDocNames = new Set();
+  for (const doc of contextDocs) {
+    if (doc === router) continue;
+    const name = parseFrontmatter(doc).name;
+    if (name) contextDocNames.add(name);
+  }
+  for (const doc of contextDocs) {
+    if (doc === router) continue;
+    const fm = parseFrontmatter(doc);
+    // keywords: required, non-empty — this is the --match routing surface.
+    const keywords = (fm.keywords || "")
+      .split(",")
+      .map((k) => k.trim())
+      .filter(Boolean);
+    if (keywords.length === 0) {
+      // Warn, not fail: pre-existing context docs created before the keyword-routing
+      // contract should not break a project's lint on sync. New docs get keywords from
+      // the seeds; backfill old ones at UPDATE-PROCESS. Dangling `related` and routing
+      // drift below remain hard failures (real breakage, opt-in only).
+      warn(`${doc} has empty/missing 'keywords' frontmatter (recommended for keyword routing; backfill at UPDATE-PROCESS — see vc-context-discovery)`);
+    }
+    // related: every listed slug must resolve to a real context: doc (no dangling cross-links).
+    const related = (fm.related || "")
+      .replace(/^\[|\]$/g, "")
+      .split(",")
+      .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+      .filter(Boolean);
+    for (const slug of related) {
+      if (!contextDocNames.has(slug)) {
+        fail(`${doc} 'related' references ${slug} which resolves to no context doc (dangling cross-link)`);
+      }
+    }
+  }
+
+  // --- generated routing block must be in sync with frontmatter on disk ---
+  if (routerText.includes("<!-- GENERATED:routing -->")) {
+    try {
+      execSync(
+        `node ${JSON.stringify(path.join(root, ".claude/skills/vc-context-discovery/scripts/discover-context.mjs"))} --check-routing`,
+        { cwd: root, stdio: ["pipe", "pipe", "pipe"] },
+      );
+    } catch {
+      fail(`${router} GENERATED:routing block is stale — run discover-context.mjs --emit-routing to rebuild`);
+    }
+  }
+
   for (const dir of fs.readdirSync(path.join(root, "process/context"), { withFileTypes: true })) {
     if (dir.isDirectory() && !getGroupEntrypoint(dir.name)) {
       fail(`process/context/${dir.name}/ is missing all-${dir.name}.md`);

.claude/skills/vc-context-discovery/SKILL.md

@@ -27,9 +27,21 @@ Document the canonical schemas for three file types used across the repo. These
 ```yaml
 name: context:{slug}
 description: "one-line scope — used by vc-context-discovery for routing"
+keywords: comma, separated, task, vocabulary, terms   # drives grep-first keyword routing
+related: [context:{other-slug}, context:{another-slug}]  # sibling/cross-group links (optional)
 date: dd-mm-yy
 ```
 
+- `keywords` — strongly recommended, non-empty. Comma-separated task-vocabulary terms an
+  agent would use to describe a task this doc serves (e.g. `session, token, refresh, jwt,
+  login`). This is the match surface for `discover-context.mjs --match`; weak/absent
+  keywords are why a relevant doc never gets routed to. Lint WARNS when empty (so existing
+  projects don't break on sync) — backfill at UPDATE-PROCESS.
+- `related` — OPTIONAL list of `context:{slug}` values for sibling docs that are usually
+  needed together (the markdown-native equivalent of cross-links). Every slug listed MUST
+  resolve to a real `context:` doc; dangling links fail lint. Discovery follows these after
+  the primary match so a task touching two domains loads both.
+
 **Plan file frontmatter schema:**
 ```yaml
 name: plan:{slug}
@@ -68,6 +80,29 @@ never throws on a missing root and exits 0 unless given a bad flag. Use `--json`
 machine-readable object. Prefer this over manually reading each file — it is deterministic
 and avoids loading huge files into context.
 
+**Keyword-first routing (deterministic, not judgment).** When the task vocabulary does not
+obviously map to a routing-table row, do not guess — let the index do the matching:
+
+```bash
+node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --match "update the user ORM model"
+```
+
+This tokenizes the task and ranks context docs by overlap with their frontmatter `keywords`,
+then appends any `related:` siblings of the top hits. Read the ranked docs in order. This is
+the fallback that fixes "the right doc existed but the agent walked past it."
+
+**Routing-table generation (drift-proof index).** The "Current Root Entry Points" and
+"Current Context Groups" tables in `all-context.md` are GENERATED from frontmatter, not
+hand-authored — they live between `<!-- GENERATED:routing -->` / `<!-- /GENERATED:routing -->`
+markers. Rebuild them after any context-org change:
+
+```bash
+node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing   # rewrites the block
+node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --check-routing  # lint: block in sync?
+```
+
+The hand-authored Task Routing Table (task-type → file) stays editorial and is NOT generated.
+
 Per **task-folder artefact colocation**, the script surfaces each task's plan, spec,
 reports, and references INSIDE its own `{slug}_{date}/` task folder; the sibling
 `reports/`/`references/` dirs are deprecated and only hold legacy artefacts.
@@ -86,9 +121,9 @@ Use these steps only if the script above fails or is unavailable.
 
 **Step 5.** If no feature name was provided, run `find process/general-plans/active/ -type f | sort` to surface any active plans relevant to the current task. Note: plan files are inside `{slug}_{date}/` task subfolders — look one level deep for `*_PLAN_*.md` files.
 
-**Step 6.** From the routing table in `all-context.md`, identify the context group files relevant to the current task domain (e.g. `tests`, `container`, `infra`, `skills`, `uxui`, `workflows`). Do NOT read every context file — only the ones the routing table says apply to this domain.
+**Step 6.** From the routing table in `all-context.md`, identify the context group files relevant to the current task domain (e.g. `tests`, `container`, `infra`, `skills`, `uxui`, `workflows`). Do NOT read every context file — only the ones the routing table says apply to this domain. If no row obviously matches, run `discover-context.mjs --match "<task>"` and use its ranked keyword hits instead of guessing.
 
-**Step 7.** Read the domain context file(s) identified in step 6. Each `all-{group}.md` is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task.
+**Step 7.** Read the domain context file(s) identified in step 6. Each `all-{group}.md` is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task. Then load any `related:` siblings of the docs you read — a task spanning two domains (e.g. auth + tests) needs both, and `related` is how the cross-domain link is declared.
 
 **Step 8.** Frontmatter extraction: For each file in the discovered set, if the file has YAML frontmatter (a `---` block at top), extract the `name`, `description`, and `date` fields. Surface in output as `"[path] (name: X — description: Y)"`. Files without frontmatter: surface path only (no error, do not skip them).
 
@@ -142,9 +177,9 @@ emitted or run. See `03-session-start.md` for the matching field table.
 
 After collecting file paths, read YAML frontmatter from each file where present.
 
-Surface the following fields alongside path: `name`, `description`, `date`, `type`, `feature`, `phase`.
+Surface the following fields alongside path: `name`, `description`, `keywords`, `related`, `date`, `type`, `feature`, `phase`.
 
-Use the `description` field for routing decisions instead of filename inference.
+Use the `description` and `keywords` fields for routing decisions instead of filename inference.
 
 Group plan files by their `feature` field value.
 

.claude/skills/vc-context-discovery/scripts/discover-context.mjs

@@ -12,10 +12,23 @@ const root = execSync("git rev-parse --show-toplevel").toString().trim();
 const args = process.argv.slice(2);
 let feature = null;
 let asJson = false;
+let matchQuery = null;
+let emitRouting = false;
+let checkRouting = false;
 for (let i = 0; i < args.length; i++) {
   const a = args[i];
   if (a === "--json") asJson = true;
-  else if (a === "--feature") {
+  else if (a === "--emit-routing") emitRouting = true;
+  else if (a === "--check-routing") checkRouting = true;
+  else if (a === "--match") {
+    matchQuery = args[++i];
+    if (!matchQuery) {
+      console.error("--match requires a value");
+      process.exit(2);
+    }
+  } else if (a.startsWith("--match=")) {
+    matchQuery = a.slice("--match=".length);
+  } else if (a === "--feature") {
     feature = args[++i];
     if (!feature) {
       console.error("--feature requires a value");
@@ -97,9 +110,23 @@ function readFrontmatter(relPath) {
     }
   }
 
+  // keywords: comma-separated scalar -> array of lowercase terms
+  const keywords = (top.keywords ?? "")
+    .split(",")
+    .map((k) => k.trim().toLowerCase())
+    .filter(Boolean);
+  // related: inline YAML list `[context:a, context:b]` -> array of slug strings
+  const related = (top.related ?? "")
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+
   return {
     name: top.name ?? null,
     description: top.description ?? null,
+    keywords,
+    related,
     date: top.date ?? null,
     type: top.type ?? metadata.type ?? null,
     feature: top.feature ?? metadata.feature ?? null,
@@ -126,6 +153,135 @@ if (feature) {
   featureFiles = walk(`process/features/${feature}`).map(describe);
 }
 
+// --- keyword matching + routing generation ---------------------------------
+const ROUTER = "process/context/all-context.md";
+const ROUTING_START = "<!-- GENERATED:routing -->";
+const ROUTING_END = "<!-- /GENERATED:routing -->";
+
+function contextDocsWithFm() {
+  return contextFiles.filter((d) => d.path.endsWith(".md") && d.fm && d.fm.hasFrontmatter);
+}
+
+function groupOf(relPath) {
+  // process/context/{group}/all-{group}.md -> {group}; root all-context.md -> null
+  const rest = relPath.replace(/^process\/context\//, "");
+  const parts = rest.split(path.sep);
+  return parts.length > 1 ? parts[0] : null;
+}
+
+function groupEntrypoints() {
+  return contextDocsWithFm()
+    .filter((d) => /(^|\/)all-[^/]+\.md$/.test(d.path) && groupOf(d.path))
+    .sort((a, b) => a.path.localeCompare(b.path));
+}
+
+function buildRoutingBlock() {
+  const eps = groupEntrypoints();
+  const rootRows = [
+    "| `process/context/all-context.md` | any substantial planning, research, review, or implementation task |",
+    ...eps.map((d) => `| \`${d.path}\` | ${d.fm.readWhen || d.fm.description || "—"} |`),
+  ];
+  const groupRows = eps.length
+    ? eps.map((d) => `| \`${groupOf(d.path)}/\` | \`${d.path}\` | ${d.fm.description || "—"} |`)
+    : ["| (no groups yet — populated during STUDY phase, then regenerated by `--emit-routing`) | | |"];
+
+  return [
+    ROUTING_START,
+    "| File | Read when |",
+    "|---|---|",
+    ...rootRows,
+    "",
+    "## Current Context Groups",
+    "",
+    "| Group | Entry point | Scope |",
+    "|---|---|---|",
+    ...groupRows,
+    ROUTING_END,
+  ].join("\n");
+}
+
+function currentRoutingBlock(text) {
+  const s = text.indexOf(ROUTING_START);
+  const e = text.indexOf(ROUTING_END);
+  if (s === -1 || e === -1 || e < s) return null;
+  return text.slice(s, e + ROUTING_END.length);
+}
+
+if (emitRouting || checkRouting) {
+  if (!fs.existsSync(path.join(root, ROUTER))) {
+    process.stderr.write(`[bare-kit mode] ${ROUTER} absent — nothing to ${emitRouting ? "emit" : "check"}.\n`);
+    process.exit(0);
+  }
+  const text = fs.readFileSync(path.join(root, ROUTER), "utf8");
+  const existing = currentRoutingBlock(text);
+  if (existing === null) {
+    console.error(`${ROUTER} has no <!-- GENERATED:routing --> markers; cannot manage routing block.`);
+    process.exit(2);
+  }
+  const fresh = buildRoutingBlock();
+  if (checkRouting) {
+    if (existing.trim() !== fresh.trim()) {
+      console.error(`${ROUTER} routing block is STALE — run discover-context.mjs --emit-routing to rebuild.`);
+      process.exit(1);
+    }
+    console.log(`${ROUTER} routing block is in sync.`);
+    process.exit(0);
+  }
+  fs.writeFileSync(path.join(root, ROUTER), text.replace(existing, fresh));
+  console.log(`Rewrote routing block in ${ROUTER} (${groupEntrypoints().length} group entrypoint(s)).`);
+  process.exit(0);
+}
+
+if (matchQuery) {
+  const tokens = (matchQuery.toLowerCase().match(/[a-z0-9]+/g) || []).filter((t) => t.length > 2);
+  const scored = contextDocsWithFm()
+    .map((d) => {
+      const kws = d.fm.keywords || [];
+      let score = 0;
+      const hits = [];
+      for (const t of tokens) {
+        if (kws.some((k) => k === t || k.includes(t) || t.includes(k))) { score += 1; hits.push(t); }
+      }
+      return { d, score, hits };
+    })
+    .filter((x) => x.score > 0)
+    .sort((a, b) => b.score - a.score || a.d.path.localeCompare(b.d.path));
+
+  // append related siblings of the top hits (deduped, not already matched)
+  const matchedPaths = new Set(scored.map((x) => x.d.path));
+  const byName = new Map(contextDocsWithFm().map((d) => [d.fm.name, d]));
+  const siblings = [];
+  for (const { d } of scored) {
+    for (const rel of d.fm.related || []) {
+      const sib = byName.get(rel);
+      if (sib && !matchedPaths.has(sib.path)) {
+        matchedPaths.add(sib.path);
+        siblings.push({ from: d.fm.name, sib });
+      }
+    }
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify({
+      query: matchQuery,
+      matches: scored.map((x) => ({ path: x.d.path, score: x.score, hits: x.hits, name: x.d.fm.name, description: x.d.fm.description })),
+      related: siblings.map((s) => ({ path: s.sib.path, name: s.sib.fm.name, via: s.from })),
+    }, null, 2));
+    process.exit(0);
+  }
+
+  const out = [`Keyword matches for: "${matchQuery}" (read in order)`];
+  if (scored.length === 0) out.push("  (no keyword matches — fall back to all-context.md routing table)");
+  for (const x of scored) out.push(`  [${x.score}] ${x.d.path} — ${x.d.fm.description ?? "—"}  (hits: ${x.hits.join(", ")})`);
+  if (siblings.length) {
+    out.push("");
+    out.push("Related siblings (load alongside the above):");
+    for (const s of siblings) out.push(`  ${s.sib.path} — ${s.sib.fm.description ?? "—"}  (related via ${s.from})`);
+  }
+  console.log(out.join("\n"));
+  process.exit(0);
+}
+
 // --- output ----------------------------------------------------------------
 function line(d) {
   if (d.fm && (d.fm.name || d.fm.description)) {

.claude/skills/vc-generate-context/references/generate-context.md

@@ -87,9 +87,10 @@ Use this table to determine which context groups to create during `standalone-fu
 
 ## Validation
 
-After updating `process/context/all-context.md`, run:
+After updating `process/context/all-context.md`, regenerate the routing tables from frontmatter, then validate:
 
 ```bash
+node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing
 node .claude/skills/vc-generate-context/scripts/validate-all-context.mjs
 ```
 
@@ -147,9 +148,8 @@ When populating `all-context.md` from seed templates or from a fresh scan, write
 1. **Title**: Replace the project name placeholder with the actual project name.
 2. **Project description**: Use the user's own words when available (from vc-setup's ASK step). Supplement with what the code scan reveals. The user's description should be prominent, not buried.
 3. **Quick Start section**: Keep the generic routing instructions from the template.
-4. **Current Root Entry Points table**: Populate with actual context files that were created.
-5. **Current Context Groups table**: Populate with groups created by the context group detection step (those groups whose `all-{group}.md` files were just written).
-6. **Task Routing table**: Fill based on what context groups exist, mapping task types to the relevant entry points.
+4. **Current Root Entry Points table** and **Current Context Groups table**: do NOT hand-fill these. They live between `<!-- GENERATED:routing -->` markers and are generated from each group doc's frontmatter. First ensure every `all-{group}.md` you wrote has complete frontmatter (`name: context:all-{group}`, `description`, a non-empty `keywords` list of task-vocabulary terms, optional `related: [context:{slug}]` siblings), then run `node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing` to populate both tables.
+6. **Task Routing table**: hand-author this (it maps editorial task types → entry points). Fill based on what context groups exist.
 7. **Repository Structure**: Write actual directory tree output (2-3 levels deep, showing key directories and files).
 8. **Technology Stack**: Write specific framework names, versions, and combinations discovered during analysis.
 9. **Key Patterns and Conventions**: Document actual patterns found in the codebase (error handling, state management, API patterns, naming conventions, import aliases). Include conventions the user mentioned.

process/_seeds/context/_all-group-template.md.seed

@@ -1,3 +1,11 @@
+---
+name: context:all-{{group}}
+description: "{{group_scope_short}} — the {{group_name}} group entrypoint/router"
+keywords: {{group}}, (add the task-vocabulary terms an agent would use for this domain)
+related: []
+date: (dd-mm-yy)
+---
+
 # {{group_name}} Context
 
 This file is the canonical {{group_name}} context entrypoint for {{project_name}}.
@@ -15,8 +23,9 @@ To use: copy this file to `process/context/{group}/all-{group}.md`, then replace
 - `{{group_scope_short}}` with a brief scope phrase (e.g., "schema changes, migrations, or query patterns")
 - `{{project_name}}` with the project name
 - Fill in each section with real project-specific content
+- Fill in the YAML frontmatter at the top: a non-empty `keywords` list (task-vocabulary terms — this is what `discover-context.mjs --match` ranks against) and any `related: [context:{slug}]` siblings usually needed alongside this group. Lint warns on empty keywords and fails on dangling related slugs.
 
-Every `all-{group}.md` entrypoint MUST have these sections: Scope, Read When, Quick Routing, Source Paths, Update Triggers.
+Every `all-{group}.md` entrypoint MUST have frontmatter (`name`, `description`, `keywords`, `date`) plus these sections: Scope, Read When, Quick Routing, Source Paths, Update Triggers.
 
 ---