feat: add frontmatter-completeness drift checker

Warn when context/ or patterns/ files lack recommended name,
description, or last_updated. Closes #53.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: root

CHANGELOG.md

@@ -6,9 +6,10 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 - **todo-fixme drift checker** — flags unresolved `TODO` / `FIXME` markers in scaffold markdown.
+- **frontmatter-completeness drift checker** — warns when `context/` or `patterns/` files lack recommended `name`, `description`, or `last_updated` frontmatter.
 
 ### Changed
-- README and CONTRIBUTING now list all 10 drift checkers (including `tool-config-sync` and `todo-fixme`).
+- README and CONTRIBUTING now list all drift checkers (including `tool-config-sync`, `todo-fixme`, and `frontmatter-completeness`).
 
 ## [0.3.5] - 2026-05-14
 

README.md

@@ -96,7 +96,7 @@ Editable source: [docs/diagrams/context-routing.excalidraw](docs/diagrams/contex
 
 ## Drift Detection
 
-Ten checkers validate your scaffold against the real codebase. Zero tokens, zero AI.
+Eleven checkers validate your scaffold against the real codebase. Zero tokens, zero AI.
 
 | Checker | What it catches |
 |---------|----------------|
@@ -110,6 +110,7 @@ Ten checkers validate your scaffold against the real codebase. Zero tokens, zero
 | **script-coverage** | `package.json` scripts not mentioned in any scaffold file |
 | **tool-config-sync** | Installed AI tool config files (e.g. `CLAUDE.md`, `.cursorrules`) out of sync with each other |
 | **todo-fixme** | Unresolved `TODO` / `FIXME` markers left in scaffold markdown |
+| **frontmatter-completeness** | Missing `name`, `description`, or `last_updated` in `context/` and `patterns/` files |
 
 Scoring starts at 100. mex deducts 10 per error, 3 per warning, and 1 per info.
 

src/drift/checkers/frontmatter-completeness.ts

@@ -0,0 +1,33 @@
+import type { DriftIssue, ScaffoldFrontmatter } from "../../types.js";
+
+const RECOMMENDED_FIELDS = ["name", "description", "last_updated"] as const;
+
+/** Warn when context/ or patterns/ files lack recommended frontmatter fields. */
+export function checkFrontmatterCompleteness(
+  frontmatter: ScaffoldFrontmatter | null,
+  source: string
+): DriftIssue[] {
+  if (!isContextOrPatternFile(source)) return [];
+
+  const issues: DriftIssue[] = [];
+  const fm = frontmatter ?? {};
+
+  for (const field of RECOMMENDED_FIELDS) {
+    const value = fm[field];
+    if (typeof value !== "string" || value.trim() === "") {
+      issues.push({
+        code: "INCOMPLETE_FRONTMATTER",
+        severity: "warning",
+        file: source,
+        line: null,
+        message: `Missing recommended frontmatter field: ${field}`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+function isContextOrPatternFile(source: string): boolean {
+  return source.startsWith("context/") || source.startsWith("patterns/");
+}

src/drift/index.ts

@@ -15,6 +15,7 @@ import { checkCrossFile } from "./checkers/cross-file.js";
 import { checkScriptCoverage } from "./checkers/script-coverage.js";
 import { checkToolConfigSync } from "./checkers/tool-config-sync.js";
 import { checkTodoFixme } from "./checkers/todo-fixme.js";
+import { checkFrontmatterCompleteness } from "./checkers/frontmatter-completeness.js";
 
 /**
  * Default glob patterns used to locate scaffold markdown files, relative to
@@ -75,6 +76,9 @@ export async function runDriftCheck(
     const edgeIssues = checkEdges(frontmatter, filePath, source, projectRoot, scaffoldRoot);
     allIssues.push(...edgeIssues);
 
+    const frontmatterIssues = checkFrontmatterCompleteness(frontmatter, source);
+    allIssues.push(...frontmatterIssues);
+
     // Staleness check
     const stalenessIssues = await checkStaleness(
       source,
@@ -86,6 +90,7 @@ export async function runDriftCheck(
     allIssues.push(...stalenessIssues);
 
     checkerIssueCounts.push([`edges:${source}`, edgeIssues.length]);
+    checkerIssueCounts.push([`frontmatter-completeness:${source}`, frontmatterIssues.length]);
     checkerIssueCounts.push([`staleness:${source}`, stalenessIssues.length]);
   }
 

src/types.ts

@@ -95,7 +95,8 @@ export type IssueCode =
   | "INDEX_ORPHAN_ENTRY"
   | "UNDOCUMENTED_SCRIPT"
   | "TOOL_CONFIG_DRIFT"
-  | "TODO_FIXME";
+  | "TODO_FIXME"
+  | "INCOMPLETE_FRONTMATTER";
 
 export interface DriftIssue {
   code: IssueCode;

test/checkers.test.ts

@@ -15,6 +15,7 @@ import { checkCrossFile } from "../src/drift/checkers/cross-file.js";
 import { checkIndexSync } from "../src/drift/checkers/index-sync.js";
 import { checkToolConfigSync } from "../src/drift/checkers/tool-config-sync.js";
 import { checkTodoFixme } from "../src/drift/checkers/todo-fixme.js";
+import { checkFrontmatterCompleteness } from "../src/drift/checkers/frontmatter-completeness.js";
 import type { Claim, ScaffoldFrontmatter } from "../src/types.js";
 
 vi.mock("../src/git.js", () => ({
@@ -468,3 +469,39 @@ describe("checkTodoFixme", () => {
     expect(issues.map((i) => i.line)).toEqual([1, 1]);
   });
 });
+
+// ── Frontmatter completeness ──
+
+describe("checkFrontmatterCompleteness", () => {
+  it("warns on missing recommended fields in context/", () => {
+    const issues = checkFrontmatterCompleteness(
+      { name: "Auth" },
+      "context/auth.md"
+    );
+    expect(issues).toHaveLength(2);
+    expect(issues.every((i) => i.severity === "warning")).toBe(true);
+    expect(issues.map((i) => i.message)).toEqual(
+      expect.arrayContaining([
+        "Missing recommended frontmatter field: description",
+        "Missing recommended frontmatter field: last_updated",
+      ])
+    );
+  });
+
+  it("passes when all recommended fields are present", () => {
+    const issues = checkFrontmatterCompleteness(
+      {
+        name: "Auth",
+        description: "Authentication overview",
+        last_updated: "2026-06-01",
+      },
+      "patterns/auth.md"
+    );
+    expect(issues).toHaveLength(0);
+  });
+
+  it("ignores ROUTER.md and other scaffold files", () => {
+    const issues = checkFrontmatterCompleteness(null, "ROUTER.md");
+    expect(issues).toHaveLength(0);
+  });
+});