@1agh/maude 0.27.0 → 0.28.1

package/plugins/design/dev-server/use-canvas-activity.tsx

@@ -0,0 +1,252 @@
+/**
+ * @file       use-canvas-activity.tsx — Phase 13 / DDR-029 activity context.
+ * @scope      plugins/design/dev-server/use-canvas-activity.tsx
+ * @purpose    Iframe-runtime React context fed by the server's `activity` WS
+ *             messages. `DCArtboard` reads it to render the "agent works here"
+ *             overlay on the artboards being edited right now.
+ *
+ * The bridge: the canvas-shell harness (`templates/_shell.html`) owns the WS
+ * connection and re-dispatches every `{ type:'activity', … }` message as a
+ * `maude:activity` CustomEvent on `document` (the same pattern used for
+ * `maude:meta-refreshed`). This provider subscribes to that event — no second
+ * socket, and trivially testable (dispatch the event in a test). In-memory only:
+ * activity is ephemeral, never persisted.
+ */
+
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+/** Cross-fade window after a file flips `idle` before its overlay is removed. */
+export const ACTIVITY_FADE_MS = 200;
+
+/** Wire shape of a server `activity` message (snake_case, matches activity.ts). */
+export interface ActivityMessage {
+  type?: 'activity';
+  file: string;
+  status: 'active' | 'idle';
+  artboard_ids?: string[] | null;
+  ts: string;
+}
+
+interface ActivityEntry {
+  status: 'active' | 'idle';
+  artboardIds: string[] | null;
+  ts: string;
+}
+
+type ActivityMap = Record<string, ActivityEntry>;
+
+/** What `useCanvasActivity()` returns for a given canvas file. */
+export interface CanvasActivity {
+  /** An entry exists (file is active OR within the post-idle fade window). */
+  present: boolean;
+  /** The file is currently being edited (drives the pulse). */
+  active: boolean;
+  /** Scoped artboard ids, or null = file-level (every artboard lights up). */
+  artboardIds: string[] | null;
+  /** Basename of the canvas file, for the badge label. */
+  fileLabel: string;
+}
+
+interface ActivityContextValue {
+  map: ActivityMap;
+  /** This canvas's design-root-relative key (server-message keyspace). */
+  currentKey: string;
+  normalizeKey: (file: string) => string;
+}
+
+const ActivityContext = createContext<ActivityContextValue | null>(null);
+
+// ---------------------------------------------------------------------------
+// Pure helpers — exported for unit tests.
+
+/**
+ * Normalize a canvas path to the server's activity keyspace: design-root-
+ * relative, slash-normalized, no leading slash. Accepts the canonical form
+ * (`ui/Foo.tsx`) or the designRel-prefixed form (`.design/ui/Foo.tsx`) that
+ * `mountCanvas` passes — stripping `designRel` when known.
+ */
+export function activityKey(file: string, designRel?: string): string {
+  let s = (file ?? '').replace(/\\/g, '/').replace(/^\/+/, '');
+  const dr = (designRel ?? '').replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+  if (dr && s.startsWith(`${dr}/`)) s = s.slice(dr.length + 1);
+  return s;
+}
+
+/** Pure reducer: fold one activity message into the map. */
+export function applyActivityChange(prev: ActivityMap, change: ActivityMessage): ActivityMap {
+  if (!change || typeof change.file !== 'string' || !change.file) return prev;
+  return {
+    ...prev,
+    [change.file]: {
+      status: change.status === 'active' ? 'active' : 'idle',
+      artboardIds: Array.isArray(change.artboard_ids) ? change.artboard_ids : null,
+      ts: typeof change.ts === 'string' ? change.ts : '',
+    },
+  };
+}
+
+/** True when an artboard id is in scope for a change (null scope = all). */
+export function matchesArtboard(artboardIds: string[] | null, id: string): boolean {
+  return artboardIds === null || artboardIds.includes(id);
+}
+
+function basename(key: string): string {
+  const i = key.lastIndexOf('/');
+  return i >= 0 ? key.slice(i + 1) : key;
+}
+
+function readDesignRel(explicit?: string): string | undefined {
+  if (explicit) return explicit;
+  if (typeof window !== 'undefined') {
+    const w = window as unknown as { __canvas_design_rel__?: string };
+    if (typeof w.__canvas_design_rel__ === 'string') return w.__canvas_design_rel__;
+  }
+  return undefined;
+}
+
+/**
+ * Seed the map from `window.__maude_activity_seed__` — the WS-open snapshot the
+ * shell stashes (raw server `activity.state`, keyed design-root-relative with a
+ * camelCase `artboardIds`). Load-bearing after the HMR reload a canvas edit
+ * triggers: the snapshot can land before React mounts, so the dispatched event
+ * is missed and only this synchronous read recovers the in-flight overlay.
+ */
+function readActivitySeed(): ActivityMap {
+  if (typeof window === 'undefined') return {};
+  const w = window as unknown as {
+    __maude_activity_seed__?: Record<
+      string,
+      { status?: 'active' | 'idle'; ts?: string; artboardIds?: string[] | null }
+    >;
+  };
+  const seed = w.__maude_activity_seed__;
+  if (!seed || typeof seed !== 'object') return {};
+  const out: ActivityMap = {};
+  for (const file of Object.keys(seed)) {
+    const e = seed[file];
+    if (!e || e.status !== 'active') continue; // only resurrect active overlays
+    out[file] = {
+      status: 'active',
+      artboardIds: Array.isArray(e.artboardIds) ? e.artboardIds : null,
+      ts: typeof e.ts === 'string' ? e.ts : '',
+    };
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+
+export interface CanvasActivityProviderProps {
+  /** This canvas's file (designRel-prefixed or design-root-relative). */
+  file?: string;
+  /** designRel for key normalization; defaults to `window.__canvas_design_rel__`. */
+  designRel?: string;
+  /** Seed (snapshot / tests). Keyed by design-root-relative path. */
+  initialState?: ActivityMap;
+  children: ReactNode;
+}
+
+export function CanvasActivityProvider({
+  file,
+  designRel,
+  initialState,
+  children,
+}: CanvasActivityProviderProps) {
+  const dr = readDesignRel(designRel);
+  const currentKey = useMemo(() => {
+    if (file) return activityKey(file, dr);
+    // No explicit file (the canvas-lib mount path) → read the design-root-
+    // relative canvas path the shell stamps on window. It already matches the
+    // server's activity keyspace, so no normalization is needed.
+    if (typeof window !== 'undefined') {
+      const w = window as unknown as { __canvas_rel__?: string };
+      if (typeof w.__canvas_rel__ === 'string' && w.__canvas_rel__) return w.__canvas_rel__;
+    }
+    return '';
+  }, [file, dr]);
+  const [map, setMap] = useState<ActivityMap>(() => initialState ?? readActivitySeed());
+  // Per-file removal timers for the post-idle cross-fade.
+  const fadeTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+  useEffect(() => {
+    if (typeof document === 'undefined') return;
+    const timers = fadeTimers.current;
+
+    function onActivity(ev: Event) {
+      const detail = (ev as CustomEvent<ActivityMessage>).detail;
+      if (!detail || typeof detail.file !== 'string') return;
+      setMap((prev) => applyActivityChange(prev, detail));
+
+      const pending = timers.get(detail.file);
+      if (pending) {
+        clearTimeout(pending);
+        timers.delete(detail.file);
+      }
+      if (detail.status === 'idle') {
+        // Keep the (now-idle) entry around briefly so the overlay cross-fades
+        // out instead of snapping off, then drop it.
+        const ts = detail.ts;
+        const t = setTimeout(() => {
+          timers.delete(detail.file);
+          setMap((prev) => {
+            const entry = prev[detail.file];
+            // Only remove if it's still the same idle entry (not re-activated).
+            if (!entry || entry.status !== 'idle' || entry.ts !== ts) return prev;
+            const { [detail.file]: _drop, ...rest } = prev;
+            return rest;
+          });
+        }, ACTIVITY_FADE_MS);
+        timers.set(detail.file, t);
+      }
+    }
+
+    document.addEventListener('maude:activity', onActivity as EventListener);
+    return () => {
+      document.removeEventListener('maude:activity', onActivity as EventListener);
+      for (const t of timers.values()) clearTimeout(t);
+      timers.clear();
+    };
+  }, []);
+
+  const value = useMemo<ActivityContextValue>(
+    () => ({ map, currentKey, normalizeKey: (f: string) => activityKey(f, dr) }),
+    [map, currentKey, dr]
+  );
+
+  return <ActivityContext.Provider value={value}>{children}</ActivityContext.Provider>;
+}
+
+const EMPTY: CanvasActivity = {
+  present: false,
+  active: false,
+  artboardIds: null,
+  fileLabel: '',
+};
+
+/**
+ * Activity state for a canvas. With no argument, returns the current canvas's
+ * activity (the provider knows its own file); pass a `file` to query another.
+ * Returns an inert value outside the provider (legacy / specimen mounts), so the
+ * overlay simply never renders there.
+ */
+export function useCanvasActivity(file?: string): CanvasActivity {
+  const ctx = useContext(ActivityContext);
+  if (!ctx) return EMPTY;
+  const key = file != null ? ctx.normalizeKey(file) : ctx.currentKey;
+  if (!key) return EMPTY;
+  const entry = ctx.map[key];
+  return {
+    present: !!entry,
+    active: entry?.status === 'active',
+    artboardIds: entry?.artboardIds ?? null,
+    fileLabel: basename(key),
+  };
+}

package/plugins/design/dev-server/use-collab.tsx

@@ -16,9 +16,11 @@
  *     <CollabProvider> never resolve these specifiers and pay zero bundle cost.
  */
 
+import * as decoding from 'lib0/decoding';
+import * as encoding from 'lib0/encoding';
 import {
-  type ReactNode,
   createContext,
+  type ReactNode,
   useCallback,
   useContext,
   useEffect,
@@ -26,9 +28,6 @@ import {
   useRef,
   useState,
 } from 'react';
-
-import * as decoding from 'lib0/decoding';
-import * as encoding from 'lib0/encoding';
 import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate } from 'y-protocols/awareness';
 import { readSyncMessage, writeSyncStep1, writeUpdate } from 'y-protocols/sync';
 import * as Y from 'yjs';

package/plugins/design/dev-server/use-selection-set.tsx

@@ -17,8 +17,8 @@
  */
 
 import {
-  type ReactNode,
   createContext,
+  type ReactNode,
   useCallback,
   useContext,
   useEffect,

package/plugins/design/dev-server/use-tool-mode.tsx

@@ -12,8 +12,8 @@
  */
 
 import {
-  type ReactNode,
   createContext,
+  type ReactNode,
   useCallback,
   useContext,
   useEffect,

package/plugins/design/dev-server/use-undo-stack.tsx

@@ -18,8 +18,8 @@
  */
 
 import {
-  type ReactNode,
   createContext,
+  type ReactNode,
   useCallback,
   useContext,
   useEffect,
@@ -31,13 +31,13 @@ import {
 import {
   type CommandRecord,
   type CommandSinks,
-  type EditCommand,
-  type UndoStackState,
   canRedo as canRedoOf,
   canUndo as canUndoOf,
+  type EditCommand,
   loadStackState,
   rebuildCommand,
   saveStackState,
+  type UndoStackState,
   undoReducer,
 } from './undo-stack.ts';
 
@@ -349,7 +349,6 @@ export function useUndoSinks(): UndoSinksValue {
   return useContext(UndoSinksContext) ?? NOOP_SINKS;
 }
 
-export { UndoStackContext, UndoSinksContext };
-
 // Re-export the EditCommand type for ergonomic single-import in consumers.
 export type { CommandRecord, EditCommand } from './undo-stack.ts';
+export { UndoSinksContext, UndoStackContext };

package/plugins/design/dev-server/ws.ts

@@ -3,6 +3,7 @@
 
 import type { ServerWebSocket, WebSocketHandler } from 'bun';
 
+import type { Activity } from './activity.ts';
 import type { Api } from './api.ts';
 import type { Collab, RoomConn } from './collab/index.ts';
 import type { Context } from './context.ts';
@@ -76,7 +77,13 @@ export interface Ws {
   clientCount(): number;
 }
 
-export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Collab): Ws {
+export function createWs(
+  ctx: Context,
+  api: Api,
+  inspect: Inspect,
+  collab: Collab,
+  activity: Activity
+): Ws {
   const clients = new Set<ServerWebSocket<WsData>>();
 
   function send(ws: ServerWebSocket<WsData>, payload: unknown) {
@@ -141,6 +148,14 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
   // Uses broadcastHmr so the segregated canvas origin's HMR-only sockets get it.
   createHmrBroadcaster(ctx, (msg) => broadcastHmr(msg));
 
+  // Phase 13 / DDR-029 — canvas activity overlay. activity.ts emits
+  // `activity:change` per file as edits land + go idle. The overlay renders
+  // INSIDE the canvas iframe, which (with the default origin split, DDR-054)
+  // holds a `canvas-hmr` socket — so this MUST use broadcastHmr, not broadcast,
+  // to reach it. The payload is just a canvas path + status (no secrets); it's
+  // the same exposure class the iframe already gets from `canvas-hmr` file paths.
+  ctx.bus.on('activity:change', (payload) => broadcastHmr({ type: 'activity', ...payload }));
+
   // Bind a connection to its room. Stored per-socket so close() can find the
   // right room to disconnect from. Multiplexed via ws.data.id.
   const collabConns = new Map<string, { roomSlug: string; conn: RoomConn }>();
@@ -175,7 +190,11 @@ export function createWs(ctx: Context, api: Api, inspect: Inspect, collab: Colla
         return;
       }
       clients.add(ws);
-      send(ws, { type: 'snapshot', state: inspect.state });
+      // Snapshot carries the inspector state AND the activity map so a client
+      // opening mid-edit seeds its overlay state (Phase 13). Inspector-origin
+      // sockets only — `canvas-hmr` sockets get no snapshot by design and rely
+      // on live `activity` broadcasts.
+      send(ws, { type: 'snapshot', state: inspect.state, activity: activity.state });
     },
     async close(ws) {
       if (ws.data.kind === 'collab') {

package/plugins/design/templates/_shell.html

@@ -110,6 +110,10 @@
       /* HUDs + banners */
       .dc-ai-banner,
       .dc-undo-hud,
+      /* Activity overlay — live "agent works here" chrome (Phase 13 / DDR-029) */
+      .dc-activity-rim,
+      /* HMR "holding last good" toast (Phase 13.1 / DDR-077) */
+      .dc-hmr-holding,
       /* Artboard title/label button (editor affordance, not design content) */
       .dc-artboard-label,
       /* Generic opt-in hooks for any future floating overlay */
@@ -162,6 +166,52 @@
       const tokensRel = stripDesignPrefix(params.get('tokens') || '');
       const componentsRel = stripDesignPrefix(params.get('components') || '');
       const layoutRel = stripDesignPrefix(params.get('layout') || '');
+
+      // Phase 13.1 / DDR-077 — error-resilient HMR while an agent edits. Hoisted
+      // here so the HMR client (below) can soft-reload the canvas module instead
+      // of location.reload()-ing into a half-saved (broken) build.
+      const canvasUrl = canvasRel ? ('/' + designRel + '/' + canvasRel) : null;
+      const myFileKey = canvasRel ? (designRel + '/' + canvasRel) : null;
+      // True while an `ai-activity` entry is live for THIS canvas (an agent is
+      // running /design:edit|new on it). Mirrors ai-banner's gate: parent relays
+      // ai-activity via postMessage when embedded; the own-WS path (standalone /
+      // same-origin inspector socket) is handled in connectHmr below.
+      let agentEditing = false;
+      window.addEventListener('message', (e) => {
+        // DDR-078 security follow-up: only the trusted embedding parent relays
+        // ai-activity. Reject canvas self-posts (which could flip the HMR gate)
+        // and any non-parent source. Standalone gets it via its own WS below.
+        if (e.source !== window.parent || window.parent === window) return;
+        const m = e && e.data;
+        if (!m || typeof m !== 'object' || m.dgn !== 'ai-activity') return;
+        if (myFileKey && m.file === myFileKey) agentEditing = !!m.entry;
+      });
+
+      // Soft reload — re-import the canvas module (cache-busted) and swap it in
+      // via the runtime, holding the last good render on a build/import error
+      // (no white flash). Only used when an agent is editing; manual edits keep
+      // the plain location.reload() below.
+      function softReload(version) {
+        if (!canvasUrl) { location.reload(); return; }
+        const rt = window.__maudeCanvasRuntime;
+        if (!rt || !rt.remount) { location.reload(); return; }
+        import(canvasUrl + '?v=' + (version || Date.now()))
+          .then((mod) => {
+            if (mod && typeof mod.default === 'function') {
+              rt.remount(mod.default);
+              if (rt.setHolding) rt.setHolding(false);
+            } else {
+              // No usable default export (rare) — fall back to a hard reload.
+              location.reload();
+            }
+          })
+          .catch((err) => {
+            // Build/transpile/import error → keep the current render, surface a
+            // non-destructive "holding" toast. Next good build swaps it in.
+            if (rt.setHolding) rt.setHolding(true, (err && (err.message || String(err))) || 'build error');
+            console.warn('[canvas-shell] soft-reload held last good (build error):', err);
+          });
+      }
       // Phase 6.5 — exporters pass ?hide-chrome=1 to flip the export-mode
       // stylesheet from `media="not all"` to `media="all"`, hiding the
       // dev-server overlays during capture. See `<style id="canvas-hide-chrome">`.
@@ -192,7 +242,55 @@
         ws.addEventListener('message', (ev) => {
           try {
             const msg = JSON.parse(ev.data);
-            if (!msg || msg.type !== 'canvas-hmr') return;
+            if (!msg) return;
+            // Phase 13.1 / DDR-077 — own-WS path for the agent-active gate (this
+            // socket is the inspector channel in standalone / same-origin mode;
+            // embedded canvas-hmr sockets get ai-activity via the parent's
+            // postMessage relay handled above).
+            if (msg.type === 'ai-activity') {
+              if (myFileKey && msg.file === myFileKey) agentEditing = !!msg.entry;
+              return;
+            }
+            // Phase 13 / DDR-029 — canvas activity overlay. The server pushes
+            // `{ type:'activity', file, status, artboard_ids, ts }` as edits land
+            // + go idle; the injected runtime (use-canvas-activity.tsx) listens
+            // for the `maude:activity` document event. Same-document bridge — no
+            // second socket. The `snapshot` seed re-plays the activity map for a
+            // tab that opens mid-edit (inspector-origin only).
+            if (msg.type === 'activity') {
+              // Maintain a running activity seed (shape matches the snapshot's
+              // `activity.state`: camelCase artboardIds). Load-bearing for the
+              // Phase 13.1 soft-reload: a soft remount resets the activity
+              // provider WITHOUT a page reload (so no fresh snapshot), and the
+              // provider re-seeds from this map — without it the overlay would
+              // vanish on every agent .tsx save.
+              if (!window.__maude_activity_seed__) window.__maude_activity_seed__ = {};
+              if (msg.status === 'active') {
+                window.__maude_activity_seed__[msg.file] = {
+                  status: 'active', artboardIds: msg.artboard_ids || null, ts: msg.ts,
+                };
+              } else {
+                delete window.__maude_activity_seed__[msg.file];
+              }
+              document.dispatchEvent(new CustomEvent('maude:activity', { detail: msg }));
+              return;
+            }
+            if (msg.type === 'snapshot' && msg.activity && typeof msg.activity === 'object') {
+              // Stash so the provider can seed on mount even if it isn't listening
+              // yet (the snapshot can arrive before React mounts — a real race
+              // after the HMR reload that a canvas edit triggers). Also dispatch
+              // for any provider that IS already mounted (same-origin live case).
+              window.__maude_activity_seed__ = msg.activity;
+              for (const file in msg.activity) {
+                const e = msg.activity[file];
+                if (!e) continue;
+                document.dispatchEvent(new CustomEvent('maude:activity', {
+                  detail: { type: 'activity', file: file, status: e.status, artboard_ids: e.artboardIds || null, ts: e.ts },
+                }));
+              }
+              return;
+            }
+            if (msg.type !== 'canvas-hmr') return;
             if (msg.mode === 'css') {
               const v = msg.version || Date.now();
               // Match by exact filename when we have one; otherwise refresh all.
@@ -222,7 +320,14 @@
             } else if (msg.mode === 'module' || msg.mode === 'hard') {
               // Only reload when the change touches *this* canvas (or `_lib`).
               if (msg.mode === 'hard' || !msg.file || (canvasRel && msg.file === canvasRel)) {
-                location.reload();
+                // Phase 13.1 / DDR-077 — when an agent is live-editing, soft-
+                // reload (hold last good on a broken intermediate). Manual edits
+                // (or no runtime yet) keep the plain, immediate hard reload.
+                if (agentEditing && window.__maudeCanvasRuntime && window.__maudeCanvasRuntime.remount) {
+                  softReload(msg.version);
+                } else {
+                  location.reload();
+                }
               }
             } else if (msg.mode === 'meta') {
               // Phase 8 — canvas-meta sidecar changed. Filter to our own canvas:
@@ -276,7 +381,7 @@
           document.head.appendChild(layoutLink);
         }
 
-        const canvasUrl = '/' + designRel + '/' + canvasRel;
+        // canvasUrl is hoisted above (Phase 13.1) so the HMR soft-reload can use it.
         // Phase 4 T5 — read the canvas's sibling .meta.json and stash it on
         // window so DesignCanvas can seed `layout` + `viewport` synchronously.
         // The fetch runs in parallel with imports; failure is non-fatal (the

package/plugins/design/templates/design-system-inspiration/SUB-AGENT-PROMPTS.md

@@ -1,12 +1,12 @@
 # Sub-agent prompt templates — `/design:setup-ds` Batch B + C
 
-> **Why this file exists.** Per Phase 3.7 Task 4 (and DDR-049), the sub-agent prompt templates that drive Batch B + C fan-out used to live inline in `plugins/design/skills/design-system/SKILL.md` (lines 662-797 pre-extraction). SKILL.md is 1000+ LOC; the prompts were buried. Extracting them here lets us audit + extend the prompts (and especially the three MANDATORY safety blocks below) without scrolling through unrelated bootstrap logic. The skill's "Batches B + C" step loads + interpolates from this file instead of inlining the template.
+> **Why this file exists.** Per Phase 3.7 Task 4 (and DDR-049), the sub-agent prompt templates that drive Batch B + C fan-out used to live inline in `plugins/design/skills/design-system/SKILL.md` (lines 662-797 pre-extraction). SKILL.md is 1000+ LOC; the prompts were buried. Extracting them here lets us audit + extend the prompts (and especially the four MANDATORY safety blocks below) without scrolling through unrelated bootstrap logic. The skill's "Batches B + C" step loads + interpolates from this file instead of inlining the template.
 >
 > **Sync rule** — when this file changes, the SKILL.md reference must still resolve. The Phase 3.7 risk register mandates a CI grep check: `SKILL.md` must literally contain the string `SUB-AGENT-PROMPTS.md`. Don't rename the file without updating the skill.
 
 The prompts are grouped by **slice** (matches the roster's `fanout:` block). Each section is a self-contained sub-agent brief — copy verbatim, substitute placeholders.
 
-The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEHOLDER POLICY) appear once at the top because they apply to every slice; sub-agent prompts reference them by name (`Apply ANIMATION SAFETY below`) instead of inlining.
+The four MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEHOLDER POLICY, CODE HYGIENE) appear once at the top because they apply to every slice; sub-agent prompts reference them by name (`Apply ANIMATION SAFETY below`) instead of inlining.
 
 ---
 
@@ -36,6 +36,15 @@ The three MANDATORY safety blocks (ANIMATION SAFETY, RELATIVE-URL SAFETY, PLACEH
 - **Never assume your own placeholder path is authoritative downstream.** When the roster row's `source:` is empty AND you wrote a placeholder, set `source: placeholder` in your roster update (not `source: written`). The brand-critic and the next bootstrap pass both look for `source: placeholder` rows as "consider revisiting later".
 - **Forbidden:** authoring an `S`-shaped wordmark for a product whose first letter isn't S, authoring a "hedgehog mascot" SVG because the README copy mentioned hedgehog energy. The studyfi imprint retro D-2 caught both patterns. If the production-asset sweep returned nothing AND the discovery brief didn't explicitly request a mascot, **rewrite the copy** instead of inventing the artifact.
 
+### CODE HYGIENE (mandatory — applies to EVERY TSX + CSS file in every slice)
+
+> **Why this block exists (setup-ds Round-2 / DDR-082).** These four defects all *pass a parse / transpile-only check but break at render or assert something false* — exactly the class the structural critic can't see. Each was caught by a user mid-flow, never by the loop. The reconcile-time scaffold-integrity gates in `_bootstrap.md` grep for all four; **prevent them here so the grep finds nothing.**
+
+- **No empty / stub files.** Every file you claim as `written` in the roster MUST carry real content — the JSDoc header, the `import "./<slug>.css"`, and a non-trivial default export. **Never** flip a roster row to `status: written` for a file you created empty or as a placeholder-to-fill-later. A 0-byte (or near-empty, < 20 B) specimen is a reconciliation **hard-fail**, the same severity as a `pending` row. The roster's `loc:` field is a claim that is verified against disk — report the *real* line count, never an aspirational one.
+- **CSS comment hygiene — never write `*/` inside a `/* … */` block.** A stray `*/` (e.g. inside an example selector string, a URL, or a nested-comment attempt) closes the comment early and the trailing text becomes invalid CSS → the dev-server bundle fails with "Bundle failed" and the specimen renders unstyled. CSS has **no nested comments.** If you must show a `*/` literally in demo copy, escape it in JSX text (`{'*/'}`) — never inside a `/* */` CSS comment.
+- **`React.*` requires a BINDING import.** Any use of `React.useState`, `React.useId`, `React.Fragment`, `React.useEffect`, `React.CSSProperties`, etc. MUST be backed by `import React from "react"` (default) or `import * as React from "react"` (namespace) — those are the only forms that bind the `React` identifier. A NAMED import (`import { useState } from "react"`) or a type-only import (`import type { CSSProperties } from "react"`) does **not** bind `React`, so `React.foo` still throws `ReferenceError: React is not defined` at module-eval in the browser even though it transpiles clean — a runtime crash the structural critic never sees. **Prefer named imports and call them unqualified** (`import { useId, useState } from "react"` → `useState(…)`, not `React.useState(…)`); reach for the `React.` namespace only with the default/namespace import in place. The reconcile gate flags any `React.*` whose file lacks a default/namespace React import.
+- **Contrast-claim discipline — never assert a ratio you didn't compute.** Do NOT write `✓ 4.5:1`, `✓ AAA`, `passes AA`, `7:1`, etc. in a specimen, a CSS comment, or copy **unless you actually computed it** from the real token pair (WCAG relative-luminance or APCA). A hardcoded-but-wrong ratio claim is worse than no claim — it tells the reader a failing pair is safe. If you want to *demonstrate* contrast without computing, label the swatch with the token names and the OKLCH values, not a fabricated ratio. The reconcile grep flags ratio-claim substrings for verification — an unverified claim is a gate failure.
+
 ---
 
 ## Sub-agent prompt template (slice-agnostic — used by every Batch B + C slice)
@@ -128,6 +137,10 @@ YOUR SLICE — write these {{N}} files (absolute paths):
 … (etc.)
 
 SAFETY BLOCKS — apply to every file in your slice:
+- **CODE HYGIENE** (see SUB-AGENT-PROMPTS.md). ALWAYS — applies to every TSX +
+  CSS file. No empty / stub files (report real `loc:`), no `*/` inside a CSS
+  `/* */` block, every `React.*` needs an explicit `import`, never assert a
+  contrast ratio you didn't compute. The reconcile gate greps for all four.
 - **ANIMATION SAFETY** (see SUB-AGENT-PROMPTS.md). Mandatory if your slice
   includes the `motion` specimen OR any file that uses `@keyframes` /
   `transition` / `animate`. Bounded geometry + sparkle-≤56px + infinite-alternate
@@ -189,7 +202,9 @@ ANTI-PATTERNS (graphic-design-critic blockers — guaranteed rejection)
 WHEN DONE
 After writing all {{N}} files:
   1. Update each row in {{absolute path to _scaffold-roster.yaml}}: change
-     `status: pending` → `status: written, loc: <line-count>`.
+     `status: pending` → `status: written, loc: <line-count>`. The `loc:` is the
+     REAL on-disk line count — never aspirational. An empty / stub / 0-byte file
+     flipped to `written` is a reconciliation hard-fail (see CODE HYGIENE).
   2. **Do NOT add new rows.** If you discover a missing claim (e.g. wordmark
      referenced but no logo.tsx in roster), include "ROSTER GAP: <description>"
      in your completion message. The main agent reconciles new rows.