From a209eeb0bdf3b0a1183fb2967a5b8f519b0db82a Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 30 Jul 2026 09:06:27 -0700 Subject: [PATCH 1/4] Fix DESIGN.md frontmatter coverage AI assistance: Codex reproduced the issue, implemented the focused fix, and added regression coverage. --- skill/scripts/lib/staleness-deep.mjs | 2 +- tests/doctor.test.mjs | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs index bae03bc98..ffc3987e7 100644 --- a/skill/scripts/lib/staleness-deep.mjs +++ b/skill/scripts/lib/staleness-deep.mjs @@ -126,7 +126,7 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) { return []; } const missing = ['colors', 'typography', 'components'] - .filter((section) => !model[section]); + .filter((section) => !model[section] && !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 2e120e4c2..b0c55cdd0 100644 --- a/tests/doctor.test.mjs +++ b/tests/doctor.test.mjs @@ -172,6 +172,28 @@ describe('checkDesignCoverage', () => { assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []); }); + it('counts machine-readable frontmatter as section coverage', () => { + const design = [ + '---', + 'name: X', + 'colors:', + ' ink: "#111111"', + 'typography:', + ' body:', + ' fontFamily: Inter', + 'components:', + ' button:', + ' backgroundColor: "{colors.ink}"', + '---', + '', + '# Design System: X', + '', + 'See the canonical source for prose guidance.', + '', + ].join('\n'); + assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []); + }); + it('reports nothing without a DESIGN.md', () => { assert.deepEqual(checkDesignCoverage({ design: null, parseDesignMd }), []); }); From 7a0489bd91991ba910a98da73a1d69d35dd85eb1 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 30 Jul 2026 09:23:37 -0700 Subject: [PATCH 2/4] 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 }), []); }); From de9d5438256ce4a5fba9501692f68c42d6804d33 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 30 Jul 2026 09:34:31 -0700 Subject: [PATCH 3/4] Reject scalar frontmatter coverage AI assistance: Codex validated and addressed the Greptile scalar-frontmatter review finding with regression coverage. --- skill/scripts/lib/staleness-deep.mjs | 2 +- tests/doctor.test.mjs | 23 +++++++++++++++++++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs index f406a7102..d98c97d19 100644 --- a/skill/scripts/lib/staleness-deep.mjs +++ b/skill/scripts/lib/staleness-deep.mjs @@ -123,7 +123,7 @@ function hasCoverageValue(value) { return Object.values(value).some(hasCoverageValue); } if (typeof value === 'string') return value.trim().length > 0; - return value !== null && value !== undefined; + return false; } export function checkDesignCoverage({ design, designPath, parseDesignMd }) { diff --git a/tests/doctor.test.mjs b/tests/doctor.test.mjs index 4887800df..41ab21063 100644 --- a/tests/doctor.test.mjs +++ b/tests/doctor.test.mjs @@ -216,6 +216,29 @@ describe('checkDesignCoverage', () => { assert.doesNotMatch(findings[0].summary, /typography|components/); }); + it('does not count boolean or numeric frontmatter scalars as section coverage', () => { + for (const colors of ['false', '0']) { + const design = [ + '---', + 'name: X', + `colors: ${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/); + } + }); + it('reports nothing without a DESIGN.md', () => { assert.deepEqual(checkDesignCoverage({ design: null, parseDesignMd }), []); }); From f274ca2c013a04cdafe8498661f2155ac0d0ed88 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 30 Jul 2026 09:43:58 -0700 Subject: [PATCH 4/4] Reject empty collection coverage AI assistance: Codex validated and addressed the Greptile empty-collection review finding with focused regression coverage. --- skill/scripts/lib/staleness-deep.mjs | 5 +++- tests/doctor.test.mjs | 38 ++++++++++++++++++++++++++++ 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs index d98c97d19..8981b654a 100644 --- a/skill/scripts/lib/staleness-deep.mjs +++ b/skill/scripts/lib/staleness-deep.mjs @@ -122,7 +122,10 @@ function hasCoverageValue(value) { if (value && typeof value === 'object') { return Object.values(value).some(hasCoverageValue); } - if (typeof value === 'string') return value.trim().length > 0; + if (typeof value === 'string') { + const trimmed = value.trim(); + return trimmed.length > 0 && !/^(?:\[\s*\]|\{\s*\})$/.test(trimmed); + } return false; } diff --git a/tests/doctor.test.mjs b/tests/doctor.test.mjs index 41ab21063..fbd9db19d 100644 --- a/tests/doctor.test.mjs +++ b/tests/doctor.test.mjs @@ -239,6 +239,44 @@ describe('checkDesignCoverage', () => { } }); + it('does not count empty frontmatter collection literals as section coverage', () => { + for (const colors of ['[]', '{}']) { + const design = [ + '---', + 'name: X', + `colors: ${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/); + } + }); + + it('counts populated frontmatter array literals as section coverage', () => { + const design = [ + '---', + 'name: X', + 'colors: ["#111111"]', + 'typography: [Inter]', + 'components: [button]', + '---', + '', + '# Design System: X', + '', + ].join('\n'); + assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []); + }); + it('reports nothing without a DESIGN.md', () => { assert.deepEqual(checkDesignCoverage({ design: null, parseDesignMd }), []); });