From 7a0489bd91991ba910a98da73a1d69d35dd85eb1 Mon Sep 17 00:00:00 2001
From: Paul Bakaus <paul.bakaus@gmail.com>
Date: Thu, 30 Jul 2026 09:23:37 -0700
Subject: [PATCH] Require populated frontmatter coverage

AI assistance: Codex validated and addressed the Greptile review finding with focused regression coverage.
---
 skill/scripts/lib/staleness-deep.mjs | 11 ++++++++++-
 tests/doctor.test.mjs                | 22 ++++++++++++++++++++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs
index ffc3987e7..f406a7102 100644
--- a/skill/scripts/lib/staleness-deep.mjs
+++ b/skill/scripts/lib/staleness-deep.mjs
@@ -117,6 +117,15 @@ export function checkDesignDrift({ designPath, projectRoot, threshold = 25 }) {
  * a section can be absent because it never applied, so this is reported as a
  * documentation gap for a human to judge, never as an error.
  */
+function hasCoverageValue(value) {
+  if (Array.isArray(value)) return value.some(hasCoverageValue);
+  if (value && typeof value === 'object') {
+    return Object.values(value).some(hasCoverageValue);
+  }
+  if (typeof value === 'string') return value.trim().length > 0;
+  return value !== null && value !== undefined;
+}
+
 export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   if (!design || typeof parseDesignMd !== 'function') return [];
   let model;
@@ -126,7 +135,7 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
     return [];
   }
   const missing = ['colors', 'typography', 'components']
-    .filter((section) => !model[section] && !model.frontmatter?.[section]);
+    .filter((section) => !model[section] && !hasCoverageValue(model.frontmatter?.[section]));
   if (!missing.length) return [];
   return [finding({
     id: 'design-md-coverage',
diff --git a/tests/doctor.test.mjs b/tests/doctor.test.mjs
index b0c55cdd0..4887800df 100644
--- a/tests/doctor.test.mjs
+++ b/tests/doctor.test.mjs
@@ -194,6 +194,28 @@ describe('checkDesignCoverage', () => {
     assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []);
   });
 
+  it('does not count empty frontmatter mappings as section coverage', () => {
+    const design = [
+      '---',
+      'name: X',
+      'colors:',
+      'typography:',
+      '  body:',
+      '    fontFamily: Inter',
+      'components:',
+      '  button:',
+      '    backgroundColor: "#111111"',
+      '---',
+      '',
+      '# Design System: X',
+      '',
+    ].join('\n');
+    const findings = checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd });
+    assert.deepEqual(ids(findings), ['design-md-coverage']);
+    assert.match(findings[0].summary, /no colors section/);
+    assert.doesNotMatch(findings[0].summary, /typography|components/);
+  });
+
   it('reports nothing without a DESIGN.md', () => {
     assert.deepEqual(checkDesignCoverage({ design: null, parseDesignMd }), []);
   });