From c91047d66ab10a21b60f8bfa6efe67facc2a5db1 Mon Sep 17 00:00:00 2001
From: Paul Bakaus <paul.bakaus@gmail.com>
Date: Fri, 31 Jul 2026 17:21:35 -0700
Subject: [PATCH 1/2] Fix seed design coverage

Treat Components as optional only when DESIGN.md carries the prescribed seed marker, while retaining Colors and Typography checks.

AI assistance: Codex reproduced the issue, implemented the fix, and added regression coverage under maintainer authorization.
---
 skill/scripts/lib/staleness-deep.mjs |  8 +++++++-
 tests/doctor.test.mjs                | 28 ++++++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs
index 8981b654a..53beb1b4b 100644
--- a/skill/scripts/lib/staleness-deep.mjs
+++ b/skill/scripts/lib/staleness-deep.mjs
@@ -129,6 +129,9 @@ function hasCoverageValue(value) {
   return false;
 }
 
+const SEED_DESIGN_MARKER = '<!-- SEED: established with the user before implementation; '
+  + "re-run /impeccable document once there's code to capture the actual tokens and components. -->";
+
 export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   if (!design || typeof parseDesignMd !== 'function') return [];
   let model;
@@ -137,7 +140,10 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   } catch {
     return [];
   }
-  const missing = ['colors', 'typography', 'components']
+  const requiredSections = design.includes(SEED_DESIGN_MARKER)
+    ? ['colors', 'typography']
+    : ['colors', 'typography', 'components'];
+  const missing = requiredSections
     .filter((section) => !model[section] && !hasCoverageValue(model.frontmatter?.[section]));
   if (!missing.length) return [];
   return [finding({
diff --git a/tests/doctor.test.mjs b/tests/doctor.test.mjs
index fbd9db19d..2063da2c3 100644
--- a/tests/doctor.test.mjs
+++ b/tests/doctor.test.mjs
@@ -172,6 +172,34 @@ describe('checkDesignCoverage', () => {
     assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []);
   });
 
+  it('allows Components to be absent from a marked seed document', () => {
+    const design = [
+      '<!-- SEED: established with the user before implementation; re-run /impeccable document once there\'s code to capture the actual tokens and components. -->',
+      '',
+      '# Design System: X',
+      '',
+      '## Colors', '', '### Primary', '- **Ink** (#111): Text.', '',
+      '## Typography', '', '**Body Font:** Inter', '',
+      '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
+    ].join('\n');
+    assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []);
+  });
+
+  it('still requires seed documents to cover Colors and Typography', () => {
+    const design = [
+      '<!-- SEED: established with the user before implementation; re-run /impeccable document once there\'s code to capture the actual tokens and components. -->',
+      '',
+      '# Design System: X',
+      '',
+      '## Typography', '', '**Body Font:** Inter', '',
+      '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
+    ].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, /components/);
+  });
+
   it('counts machine-readable frontmatter as section coverage', () => {
     const design = [
       '---',

From a3d7b247aabd5c731dc5bd035b0497aa6c967a71 Mon Sep 17 00:00:00 2001
From: Paul Bakaus <paul.bakaus@gmail.com>
Date: Fri, 31 Jul 2026 17:32:57 -0700
Subject: [PATCH 2/2] Cover provider seed markers

Recognize both slash- and dollar-prefixed prescribed seed markers and exercise each variant in coverage tests.

AI assistance: Codex addressed Cursor and Copilot review feedback and reran validation under maintainer authorization.
---
 skill/scripts/lib/staleness-deep.mjs |  9 ++++--
 tests/doctor.test.mjs                | 48 +++++++++++++++-------------
 2 files changed, 32 insertions(+), 25 deletions(-)

diff --git a/skill/scripts/lib/staleness-deep.mjs b/skill/scripts/lib/staleness-deep.mjs
index 53beb1b4b..2c8d6a82f 100644
--- a/skill/scripts/lib/staleness-deep.mjs
+++ b/skill/scripts/lib/staleness-deep.mjs
@@ -129,8 +129,10 @@ function hasCoverageValue(value) {
   return false;
 }
 
-const SEED_DESIGN_MARKER = '<!-- SEED: established with the user before implementation; '
-  + "re-run /impeccable document once there's code to capture the actual tokens and components. -->";
+const SEED_DESIGN_MARKERS = ['/', '$'].map((prefix) =>
+  '<!-- SEED: established with the user before implementation; '
+    + `re-run ${prefix}impeccable document once there's code to capture the actual tokens and components. -->`
+);
 
 export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   if (!design || typeof parseDesignMd !== 'function') return [];
@@ -140,7 +142,8 @@ export function checkDesignCoverage({ design, designPath, parseDesignMd }) {
   } catch {
     return [];
   }
-  const requiredSections = design.includes(SEED_DESIGN_MARKER)
+  const isSeed = SEED_DESIGN_MARKERS.some((marker) => design.includes(marker));
+  const requiredSections = isSeed
     ? ['colors', 'typography']
     : ['colors', 'typography', 'components'];
   const missing = requiredSections
diff --git a/tests/doctor.test.mjs b/tests/doctor.test.mjs
index 2063da2c3..7d801dfb8 100644
--- a/tests/doctor.test.mjs
+++ b/tests/doctor.test.mjs
@@ -173,31 +173,35 @@ describe('checkDesignCoverage', () => {
   });
 
   it('allows Components to be absent from a marked seed document', () => {
-    const design = [
-      '<!-- SEED: established with the user before implementation; re-run /impeccable document once there\'s code to capture the actual tokens and components. -->',
-      '',
-      '# Design System: X',
-      '',
-      '## Colors', '', '### Primary', '- **Ink** (#111): Text.', '',
-      '## Typography', '', '**Body Font:** Inter', '',
-      '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
-    ].join('\n');
-    assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []);
+    for (const command of ['/impeccable', '$impeccable']) {
+      const design = [
+        `<!-- SEED: established with the user before implementation; re-run ${command} document once there's code to capture the actual tokens and components. -->`,
+        '',
+        '# Design System: X',
+        '',
+        '## Colors', '', '### Primary', '- **Ink** (#111): Text.', '',
+        '## Typography', '', '**Body Font:** Inter', '',
+        '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
+      ].join('\n');
+      assert.deepEqual(checkDesignCoverage({ design, designPath: 'DESIGN.md', parseDesignMd }), []);
+    }
   });
 
   it('still requires seed documents to cover Colors and Typography', () => {
-    const design = [
-      '<!-- SEED: established with the user before implementation; re-run /impeccable document once there\'s code to capture the actual tokens and components. -->',
-      '',
-      '# Design System: X',
-      '',
-      '## Typography', '', '**Body Font:** Inter', '',
-      '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
-    ].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, /components/);
+    for (const command of ['/impeccable', '$impeccable']) {
+      const design = [
+        `<!-- SEED: established with the user before implementation; re-run ${command} document once there's code to capture the actual tokens and components. -->`,
+        '',
+        '# Design System: X',
+        '',
+        '## Typography', '', '**Body Font:** Inter', '',
+        '### Hierarchy', '- **Body** (400, 16px, 1.5): Paragraphs.', '',
+      ].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, /components/);
+    }
   });
 
   it('counts machine-readable frontmatter as section coverage', () => {