fix(design): scope working-tree checks and validate Studio

Author: Bill Leoutsakos

.github/workflows/test-build.yml

@@ -311,6 +311,7 @@ jobs:
 
       # Only findings (exit 1) are non-blocking; operational errors still fail CI.
       - name: Design conformance (warnings)
+        if: always() && steps.audit_base.outcome == 'success'
         env:
           DESIGN_BASE: ${{ steps.audit_base.outputs.ref }}
           DESIGN_HEAD: ${{ steps.audit_base.outputs.head }}

CLAUDE.md

@@ -10,9 +10,9 @@ This file (also `AGENTS.md`) holds the repo-wide rules. Area detail lives in `.c
 - **Logging**: `createLogger` from `@sim/logger`; `logger.info` / `logger.warn` / `logger.error`, never `console.log`. Inside `withRouteHandler` the logger already carries the request ID — no manual `withMetadata({ requestId })`.
 - **Comments**: TSDoc for documentation. An inline `//` only for a terse, non-obvious why, or for a script-enforced `// <tag>: <reason>` annotation (`boundary-raw-fetch`, `double-cast-allowed`, `boundary-raw-json`, `untyped-response`, `rq-lint-allow`, `client-boundary-allow`, …). No `====` separators.
 - **ID generation**: `generateId()` (UUID v4, the default) or `generateShortId(size?)` (URL-safe, 21 chars by default) from `@sim/utils/id` — never `crypto.randomUUID()`, `nanoid`, or `uuid`. Both use `crypto.getRandomValues()`, so they also work in non-secure (HTTP) browsers.
-- **Common utilities**: use the shared helpers from `@sim/utils` instead of inline implementations:
 - **Design conformance**: Run `bun run check:design --base origin/staging --working-tree` while editing product UI. Reuse suitable EMCN components and global tokens; explain intentional Extras in the PR. Design findings are advisory, while an incomplete check is an error. See `scripts/design-conformance/README.md`.
 - **Styling**: Derive product styling from central tokens, component props and recipes where they fit. Keep product composition local. Explain intentional changes to shared standards. Landing and docs are outside the product design check.
+- **Common utilities**: use the shared helpers from `@sim/utils` instead of inline implementations:
   - `sleep(ms)` from `@sim/utils/helpers` — never `new Promise(resolve => setTimeout(resolve, ms))`
   - `toError(e)` from `@sim/utils/errors` — normalize caught values to `Error`; never `e instanceof Error ? e : new Error(String(e))`
   - `getErrorMessage(e, fallback?)` from `@sim/utils/errors` — never `e instanceof Error ? e.message : 'fallback'`

package.json

@@ -120,7 +120,7 @@
     "agent-stream-docs:check": "bun run scripts/sync-agent-stream-docs.ts --check",
     "prepare": "bun husky",
     "test:workflow-sync": "bun --no-env-file scripts/test-integration.ts lib/workspaces/__integration__",
-    "type-check": "bun run type-check:design && turbo run type-check",
+    "type-check": "bun run type-check:design && bun run type-check:studio && turbo run type-check",
     "release": "bun run scripts/create-single-release.ts",
     "test:scripts": "vitest run --config scripts/vitest.config.ts",
     "check:design": "bun --no-env-file scripts/check-design-conformance.ts",

packages/emcn/src/AGENTS.md

@@ -6,4 +6,4 @@ Applies to `packages/emcn/**`. Read `.claude/rules/emcn-components.md` before ch
 - Components own their exact geometry tokens (e.g. `Button` uses `rounded-[5px]`) but never their own font-weight: every primitive inherits the document 400 and steps up only deliberately.
 - TSDoc for public components and APIs.
 
-Central component, recipe and icon changes are design-system decisions. Run `bun run check:design --base origin/staging --working-tree` and explain intended shared changes in the PR. Review warnings remain visible. See `scripts/design-conformance/README.md`.
+Central component, recipe and icon changes are design-system decisions. Run `bun run check:design --base origin/staging --working-tree` (using the actual PR target as the base) and explain intended shared changes in the PR. Review warnings remain visible. See `scripts/design-conformance/README.md`.

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

@@ -32,6 +32,7 @@ function fixture() {
   git(repo, ['init', '-q'])
   writeFileSync(path.join(repo, TOKEN_FILE), ':root{--text-body:#434343}')
   writeFileSync(path.join(repo, ui), 'const A=()=> <p className="text-[var(--text-body)]"/>')
+  writeFileSync(path.join(repo, 'README.md'), '# Fixture\n')
   const base = commit(repo)
   writeFileSync(path.join(repo, ui), 'const A=()=> <p className="text-[#434343]"/>')
   const head = commit(repo)
@@ -90,6 +91,30 @@ test('working-tree mode checks staged, unstaged and new product files without co
   expect(run(['--repo', repo, '--base', head, '--head', 'HEAD']).status).toBe(0)
 })
 
+test('working-tree mode ignores unrelated tracked and untracked files', () => {
+  const { repo, head } = fixture()
+  mkdirSync(path.join(repo, 'tools'), { recursive: true })
+  writeFileSync(path.join(repo, 'tools/notes.txt'), 'Not product styling')
+  const result = run(['--repo', repo, '--base', head, '--working-tree', '--format', 'json'])
+  expect(result.status).toBe(0)
+  const report = JSON.parse(result.stdout) as Report
+  expect(report.status).toBe('completed')
+  expect(report.findings).toHaveLength(0)
+})
+
+test('working-tree mode includes a changed central contract registry', () => {
+  const { repo } = fixture()
+  const file = 'scripts/design-conformance/contracts.json'
+  mkdirSync(path.join(repo, path.dirname(file)), { recursive: true })
+  writeFileSync(path.join(repo, file), '{"version":1}\n')
+  const base = commit(repo)
+  writeFileSync(path.join(repo, file), '{"version":2}\n')
+  const result = run(['--repo', repo, '--base', base, '--working-tree', '--format', 'json'])
+  expect(result.status).toBe(1)
+  const report = JSON.parse(result.stdout) as Report
+  expect(report.findings.some((finding) => finding.file === file)).toBe(true)
+})
+
 test('text, JSON and output files preserve finding identity and normal command exit codes', () => {
   const { repo, base, head } = fixture()
   const args = ['--repo', repo, '--base', base]

scripts/design-conformance/command.ts

@@ -22,7 +22,7 @@ import {
 } from '#design-conformance/model'
 import { githubAnnotations, githubSummary, textReport } from '#design-conformance/reporting'
 import { gitSnapshot } from '#design-conformance/system-snapshot'
-import { GitSource } from '#design-conformance/worktree-source'
+import { GitSource, inspectedSource } from '#design-conformance/worktree-source'
 
 export const repositoryRoot = fileURLToPath(new URL('../../', import.meta.url))
 const usage =
@@ -97,18 +97,21 @@ export async function checkComparison(args: CheckArguments): Promise<Report> {
 function workingChanges(before: GitSource, after: GitSource): Change[] {
   const old = new Map(before.entries.map((entry) => [entry.path, entry]))
   const current = new Map(after.entries.map((entry) => [entry.path, entry]))
-  return [...new Set([...old.keys(), ...current.keys()])].sort().flatMap((file) => {
-    const previous = old.get(file)
-    const next = current.get(file)
-    if (previous?.blob === next?.blob && previous?.mode === next?.mode) return []
-    return [
-      {
-        before: previous ?? null,
-        after: next ?? null,
-        status: previous ? (next ? 'M' : 'D') : 'A',
-      },
-    ]
-  })
+  return [...new Set([...old.keys(), ...current.keys()])]
+    .sort()
+    .filter(inspectedSource)
+    .flatMap((file) => {
+      const previous = old.get(file)
+      const next = current.get(file)
+      if (previous?.blob === next?.blob && previous?.mode === next?.mode) return []
+      return [
+        {
+          before: previous ?? null,
+          after: next ?? null,
+          status: previous ? (next ? 'M' : 'D') : 'A',
+        },
+      ]
+    })
 }
 
 /** The regular command always preserves 0/1/2; only the CI wrapper tolerates findings. */

scripts/design-conformance/worktree-source.ts

@@ -4,7 +4,7 @@ import { lstatSync, readFileSync, readlinkSync, realpathSync } from 'node:fs'
 import path from 'node:path'
 import { productScope } from '#control-analysis/scope'
 import { typographySource } from '#control-analysis/typography'
-import { centralInventory, registry } from '#design-conformance/contracts'
+import { centralInventory, isRegistry, registry } from '#design-conformance/contracts'
 import { verifiedText } from '#design-conformance/io'
 import type { Entry } from '#design-conformance/model'
 import { TOKEN_FILE } from '#design-conformance/model'
@@ -15,6 +15,13 @@ export interface SourceEntry extends Entry {
   kind: string
 }
 
+/** Files whose authored bytes participate in local design analysis. */
+export const inspectedSource = (file: string) =>
+  centralInventory(file) ||
+  isRegistry(file) ||
+  productScope(file) === 'check' ||
+  typographySource(file)
+
 /** Git tree/blob reads only: no checkout, textconv, filters, hooks or application imports. */
 export class GitSource {
   readonly mode: 'snapshot' | 'working-tree'
@@ -73,7 +80,7 @@ export class GitSource {
       if (stat.isDirectory())
         return [{ path: file, mode: '160000', kind: 'commit', blob: '', bytes: 0 }]
       const mode = stat.isSymbolicLink() ? '120000' : stat.mode & 0o111 ? '100755' : '100644'
-      if (!centralInventory(file) && productScope(file) !== 'check' && !typographySource(file))
+      if (!inspectedSource(file))
         return [{ path: file, mode, kind: 'blob', blob: '', bytes: stat.size }]
       if (realpathSync(path.dirname(absolute)) !== path.dirname(absolute))
         throw new Error(`Source has a symlinked parent directory: ${file}`)