refactor(design): publish source contracts in scan report

Author: Bill Leoutsakos

.agents/skills/emcn-design-review/SKILL.md

@@ -10,7 +10,7 @@ User arguments: $ARGUMENTS
 
 Interpret the arguments as the product UI scope (default: current changes) and an optional `fix=true|false` mode (default: `false`). When `fix=false`, explain proposed changes without applying them.
 
-1. When EMCN, global styles, recipes or design ownership metadata change, run `bun run design:generate` and commit `scripts/design-conformance/contracts.generated.json` with the source. `bun run check:design-generated` checks freshness without writing. Regeneration does not hide the originating design-system finding.
+1. When EMCN, global styles, recipes or design ownership metadata change, run the diff check in step 2. It derives facts from each source revision, so the originating design-system change remains visible without a committed metadata file.
 2. During UI work, run `bun run check:design --base origin/staging --working-tree` from the repo root, substituting the actual PR target for `origin/staging`. After committing, use `--head HEAD` for the immutable PR comparison. Exit 1 means findings to review; exit 2 means the check failed and must be repaired or reported. CI is warning-only for findings and fails on incomplete analysis.
 3. For each new finding, inspect the cited source, the applicable public EMCN export in `packages/emcn/src/index.ts`, and tokens and recipes in `apps/sim/app/_styles/globals.css`. Reuse a suitable component, prop, variant, or global token when it expresses the design intent. Avoid near-duplicate local colours or overriding EMCN chrome merely for convenience.
 4. A genuinely new product treatment may remain an Extra. Explain its visual intent and why existing EMCN or global styling does not fit in the PR. The check does not decide design approval and must not be silenced by adding an arbitrary token, broad exclusion, or fake component wrapper. Ask the designer or engineer when changing a shared recipe would have broad or ambiguous effects.

.agents/skills/ship/SKILL.md

@@ -102,7 +102,7 @@ When the user runs `/ship`:
 
 ## Committed design check
 
-When central EMCN sources, global styles, recipes or `@designAllow`/`@designProtect` metadata change, run `bun run design:generate`, review the result and commit `contracts.generated.json` alongside the source. `check:design-generated` is part of `check:audits`; stale output is an infrastructure error. Regeneration does not suppress the source finding.
+When central EMCN sources, global styles, recipes or `@designAllow`/`@designProtect` metadata change, run the design diff check and review its central-system findings. The checker derives metadata independently from the base and proposed source; no generated artifact needs to be committed.
 
 During product UI work, run `bun run check:design --base origin/staging --working-tree` so staged, unstaged and nonignored new files are included. Review findings against EMCN and `globals.css`; explain intentional new Extras rather than weakening the checker. After committing and before **every push**, run this from the repository root with the repository-pinned Bun version:
 

.claude/rules/emcn-components.md

@@ -21,7 +21,7 @@ The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items
 
 ## Public components and design behavior
 
-The current public exports, variants, defaults, styling slots, and relationships are generated from source in `scripts/design-conformance/contracts.generated.json`. Run `bun run design:generate` when EMCN or `globals.css` changes. Browse and interact with the visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
+The current public exports, variants, defaults, styling slots, and relationships are derived directly from source by the design check and full scanner. Run `bun run check:design --base origin/staging --working-tree` when EMCN or `globals.css` changes. Browse and interact with visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
 
 Use chip fields and triggers for product forms, and `DropdownMenu` for context and action lists. Prefer a supported prop to a `className` chrome override. A selected chip uses `active`; outer spacing belongs to its parent. A view-only value stays at full opacity and uses the read-only copy field or `ChipModalField type='copy'`, not a disabled input. `ChipModalField` owns its inner control chrome; use `type='custom'` with a title for a control it does not cover. A chip dropdown owns its chevron and supports single or multi-select through `multiple`; use chip select or combobox for searchable or grouped lists. Inline tags are labels, not pill triggers.
 
@@ -49,6 +49,6 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
 
-## Generated design contracts
+## Source-derived design contracts
 
-Run `bun run design:generate` after public API, styling, recipe or ownership changes and commit `scripts/design-conformance/contracts.generated.json` with the source. CI checks freshness through `check:design-generated`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review the diff findings after generation; they retain originating central changes. Browser reports and captures remain local, outside the repository.
+The diff check derives public API, styling, recipe and ownership facts from both source revisions; the full scan publishes current facts in `scan.json`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review central source changes in the diff findings. Browser reports and captures remain local, outside the repository.

.cursor/rules/emcn-components.mdc

@@ -22,7 +22,7 @@ The menu surface intentionally diverges from the pill: `dropdown-menu.tsx` items
 
 ## Public components and design behavior
 
-The current public exports, variants, defaults, styling slots, and relationships are generated from source in `scripts/design-conformance/contracts.generated.json`. Run `bun run design:generate` when EMCN or `globals.css` changes. Browse and interact with the visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
+The current public exports, variants, defaults, styling slots, and relationships are derived directly from source by the design check and full scanner. Run `bun run check:design --base origin/staging --working-tree` when EMCN or `globals.css` changes. Browse and interact with visual exports in the local Design Studio after `bun run studio:refresh`; do not maintain an export list here.
 
 Use chip fields and triggers for product forms, and `DropdownMenu` for context and action lists. Prefer a supported prop to a `className` chrome override. A selected chip uses `active`; outer spacing belongs to its parent. A view-only value stays at full opacity and uses the read-only copy field or `ChipModalField type='copy'`, not a disabled input. `ChipModalField` owns its inner control chrome; use `type='custom'` with a title for a control it does not cover. A chip dropdown owns its chevron and supports single or multi-select through `multiple`; use chip select or combobox for searchable or grouped lists. Inline tags are labels, not pill triggers.
 
@@ -50,6 +50,6 @@ Declare keyboard intent on the action-owning primitive; never add document-level
 
 Color tokens and icon-size conventions are canonical in `.claude/rules/sim-styling.md` — follow it rather than restating.
 
-## Generated design contracts
+## Source-derived design contracts
 
-Run `bun run design:generate` after public API, styling, recipe or ownership changes and commit `scripts/design-conformance/contracts.generated.json` with the source. CI checks freshness through `check:design-generated`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review the diff findings after generation; they retain originating central changes. Browser reports and captures remain local, outside the repository.
+The diff check derives public API, styling, recipe and ownership facts from both source revisions; the full scan publishes current facts in `scan.json`. Ownership is derived from implementation; intentional customization belongs in component TSDoc (`@designAllow <slot> <CSS properties or policy groups>`, `@designProtect` for ownership that cannot be inferred). Review central source changes in the diff findings. Browser reports and captures remain local, outside the repository.

CLAUDE.md

@@ -106,7 +106,7 @@ The `'use client'` server boundary, the app/worker runtime env split, and featur
 
 ## Styling and EMCN
 
-- Tailwind only. Inline `style` only for a genuinely dynamic value or a CSS variable. Keep component-specific styling local. Change tokens in `globals.css` deliberately when the shared design decision changes, then run `bun run design:generate`. `cn()` from `@sim/emcn` for conditional classes. `size-*` for equal height and width (icons default `size-[14px]`), never `h-N w-N`.
+- Tailwind only. Inline `style` only for a genuinely dynamic value or a CSS variable. Keep component-specific styling local. Change tokens in `globals.css` deliberately when the shared design decision changes, then run `bun run check:design --base origin/staging --working-tree`. `cn()` from `@sim/emcn` for conditional classes. `size-*` for equal height and width (icons default `size-[14px]`), never `h-N w-N`.
 - Import components, `cn`, and tokens from the `@sim/emcn` barrel; icons from `@sim/emcn/icons`; CSS modules by file path. Never deep-import other component subpaths.
 - The chip family is the canonical chrome: `ChipInput`, `ChipTextarea`, `ChipModal`/`ChipModalField`, `ChipSelect`/`ChipCombobox`/`ChipDropdown`, `ChipSwitch`, `ChipDatePicker`, `Chip`/`ChipLink`, `ChipTag`; `DropdownMenu` for context/action menus. Components own their chrome: consumers pass props (`error`, `icon`, `endAdornment`, `inputClassName`) and `className` carries only layout/sizing. Every labeled field inside a `ChipModalBody` is a `ChipModalField`.
 - Consumer rules, tokens, text scale, and modal rhythm: `.claude/rules/sim-styling.md`. Authoring components in `packages/emcn`: `.claude/rules/emcn-components.md`. Product UI copy: `.claude/rules/sim-ui-copy.md`. Marketing copy and positioning: `.claude/rules/constitution.md`.

biome.json

@@ -167,10 +167,7 @@
       }
     },
     {
-      "includes": [
-        "scripts/design-conformance/contracts.json",
-        "scripts/design-conformance/contracts.generated.json"
-      ],
+      "includes": ["scripts/design-conformance/contracts.json"],
       "formatter": {
         "enabled": false
       }

package.json

@@ -130,9 +130,7 @@
     "studio:dev": "next dev tools/design-studio --hostname 127.0.0.1 --port 3001",
     "type-check:studio": "tsc --noEmit -p tools/design-studio/tsconfig.json",
     "type-check:design": "tsc --noEmit -p scripts/design-conformance/tsconfig.json",
-    "check:agent-cli-boundary": "bun run scripts/check-agent-cli-boundary.ts",
-    "design:generate": "bun --no-env-file scripts/generate-design-contracts.ts",
-    "check:design-generated": "bun run --no-env-file scripts/generate-design-contracts.ts --check"
+    "check:agent-cli-boundary": "bun run scripts/check-agent-cli-boundary.ts"
   },
   "overrides": {
     "react": "19.2.4",

scripts/check-design-conformance-command.test.ts

@@ -8,20 +8,21 @@ import { ciRefs, warningExitCode } from '#design-conformance/ci'
 import { repositoryRoot } from '#design-conformance/command'
 import { ConformanceLinter } from '#design-conformance/conformance'
 import { contractsHash, isRegistry } from '#design-conformance/contracts'
+import { generateContracts } from '#design-conformance/generated-contracts'
 import { compareGit, git } from '#design-conformance/io'
-import { hash, type Report, TOKEN_FILE } from '#design-conformance/model'
+import { hash, inspectionFailure, type Report, TOKEN_FILE } from '#design-conformance/model'
 import {
   escapeAnnotation,
   githubAnnotations,
   githubSummary,
   textReport,
 } from '#design-conformance/reporting'
 import { snapshotHash } from '#design-conformance/system-snapshot'
+import { GitSource } from '#design-conformance/worktree-source'
 
 const temp = mkdtempSync(path.join(os.tmpdir(), 'design-command-'))
 afterAll(() => rmSync(temp, { recursive: true, force: true }))
 const cli = fileURLToPath(new URL('./check-design-conformance.ts', import.meta.url))
-const generatorCli = fileURLToPath(new URL('./generate-design-contracts.ts', import.meta.url))
 const ci = fileURLToPath(new URL('./design-conformance/ci.ts', import.meta.url))
 const ui = 'apps/sim/components/example.tsx'
 
@@ -280,8 +281,8 @@ test.each([
   ['truthy string value', "{'bg-red-500':'text-[37px]'}", ['background-color']],
   ['dynamic value', "{'p-2':active}", ['padding']],
 ] as const)(
-  'source metadata follows class map enablement through the generator CLI: %s',
-  (_name, map, protectedProperties) => {
+  'source metadata follows class map enablement through source analysis: %s',
+  async (_name, map, protectedProperties) => {
     const { repo } = fixture()
     const write = (file: string, source: string) => {
       mkdirSync(path.dirname(path.join(repo, file)), { recursive: true })
@@ -298,11 +299,7 @@ export function Example({className,...props}:HTMLAttributes<HTMLDivElement>){ret
 throw new Error('Product source must not execute')
 `
     )
-    const result = run(['--repo', repo], generatorCli)
-    expect(result.status, result.stderr).toBe(0)
-    const metadata = JSON.parse(
-      readFileSync(path.join(repo, 'scripts/design-conformance/contracts.generated.json'), 'utf8')
-    )
+    const metadata = await generateContracts(new GitSource(repo, 'HEAD', true).central())
     expect(metadata.exports.Example.slots.className.protected).toEqual(protectedProperties)
   }
 )
@@ -1055,6 +1052,7 @@ test('unchecked diagnostics preserve both sides and safely render source-authore
       side,
       context: 'className',
       reason: 'Unknown helper: <script>& value\r\n::warning::injected',
+      relevant: true,
     })
   const original = JSON.stringify(report)
   const text = textReport(report)
@@ -1070,23 +1068,45 @@ test('unchecked diagnostics preserve both sides and safely render source-authore
   expect(JSON.stringify(report)).toBe(original)
 })
 
-test('large unchecked summaries show explicit limits while logs retain every complete diagnostic', () => {
+test('large finding messages stay bounded in logs while JSON keeps full evidence', () => {
+  const report = findingReport()
+  report.findings[0].kind = 'system-change'
+  report.findings[0].before = 'a'.repeat(3000)
+  const log = textReport(report)
+  const annotation = githubAnnotations(report)[0]
+  expect(log).toContain('[truncated; see JSON]')
+  expect(log).not.toContain('a'.repeat(3000))
+  expect(annotation).toContain('[truncated; see JSON]')
+  expect(annotation).not.toContain('a'.repeat(3000))
+  expect(JSON.stringify(report)).toContain('a'.repeat(3000))
+})
+
+test('large unchecked summaries keep complete JSON evidence and bound human output', () => {
   const report = new ConformanceLinter().report(null)
   report.unchecked = Array.from({ length: 101 }, (_, index) => ({
     file: `component-${index}.tsx`,
     line: 1,
     side: 'after',
     context: '',
     reason: index === 0 ? `${'&'.repeat(2000)} complete-long-diagnostic` : `reason-${index}`,
+    relevant: true,
   }))
   const markdown = githubSummary(report)
   const text = textReport(report)
-  expect(markdown).toContain('Showing 100 of 101 diagnostics')
-  expect(markdown).toContain('[truncated; see check log]')
+  expect(markdown).toContain('Showing 20 of 101 diagnostics')
+  expect(markdown).toContain('[truncated; see JSON]')
   expect(markdown).not.toContain('complete-long-diagnostic')
   expect(markdown).not.toContain('component-100.tsx')
-  expect(text).toContain('complete-long-diagnostic')
-  expect(text).toContain('component-100.tsx:1 (after) — reason-100')
+  expect(text).toContain('101 unchecked diagnostics')
+  expect(text).not.toContain('component-100.tsx:1 (after) — reason-100')
+  expect(JSON.stringify(report)).toContain('component-100.tsx')
+})
+
+test('inspection severity is explicit and does not depend on diagnostic wording', () => {
+  expect(inspectionFailure({ reason: 'Arbitrary prose', inspection: 'failed' })).toBe(true)
+  expect(inspectionFailure({ reason: 'Parser failure in a supported but unresolved flow' })).toBe(
+    false
+  )
 })
 
 test('system edits remain flagged but are reported as design review warnings', () => {

scripts/check-design-conformance-coverage.test.ts

@@ -1,19 +1,16 @@
 /** biome-ignore-all lint/suspicious/noTemplateCurlyInString: Fixtures contain proposed source text. */
-import { readFileSync } from 'node:fs'
 import { expect, test } from 'vitest'
 import { inspectControlAnalysis } from '#control-analysis/analysis'
 import type { ControlSource } from '#control-analysis/model'
 import { ReviewCollector } from '#control-analysis/review'
 import { productScope } from '#control-analysis/scope'
 import { extract } from '#design-conformance/extract'
-import type { GeneratedContracts } from '#design-conformance/generated-contracts'
-import { inspectionFailure } from '#design-conformance/model'
+import { generateContracts } from '#design-conformance/generated-contracts'
+import { GitSource } from '#design-conformance/worktree-source'
 
 const globals = 'apps/sim/app/_styles/globals.css'
 const ui = 'apps/sim/components/example.tsx'
-const metadata = JSON.parse(
-  readFileSync('scripts/design-conformance/contracts.generated.json', 'utf8')
-) as GeneratedContracts
+const metadata = await generateContracts(new GitSource(process.cwd(), 'HEAD', true).central())
 function source(files: Record<string, string>): ControlSource {
   return {
     entries: Object.entries(files).map(([path, text]) => ({
@@ -34,7 +31,6 @@ const inspect = (files: Record<string, string>) =>
     }),
     'forward',
     undefined,
-    undefined,
     metadata
   )
 
@@ -49,6 +45,7 @@ test('browser desktop UI is checked while landing, docs, native desktop and API
     'apps/sim/app/design-studio/components/page.tsx',
     'apps/desktop/src/main.tsx',
     'apps/sim/lib/desktop/appearance.ts',
+    'apps/sim/scripts/example.tsx',
     'apps/sim/tools/generated/tool-metadata.ts',
     'apps/sim/app/api/desktop/auth/route.ts',
   ])
@@ -400,15 +397,6 @@ test.each([
   )
 })
 
-test.each([
-  'CSS assignment source is nonregular or exceeds the parsing limit',
-  'Artwork parser failure; only blob change is known',
-  'Artwork source exceeds the 2 MiB parsing limit',
-  'Artwork symlink/submodule is not followed',
-])('inspection failures are not unresolved styling: %s', (reason) => {
-  expect(inspectionFailure(reason)).toBe(true)
-})
-
 test.each(['button', 'input', 'textarea', 'select', 'section > button.action', 'button + input'])(
   'bare native CSS controls are reviewable: %s',
   (selector) => {