buildanything 2.0.0 → 2.1.1

package/src/orchestrator/hooks/context-header.ts

@@ -5,7 +5,7 @@ export interface ContextHeaderInput {
   projectType: 'web' | 'ios';
   phase: number;
   iosFeatures?: Record<string, boolean>;
-  visualDnaPath?: string;  // path to visual-dna.md
+  visualDnaPath?: string;  // path to DESIGN.md (repo root) — DNA lives in `## Overview > ### Brand DNA` block
 }
 
 export interface RenderedHeader {
@@ -13,8 +13,9 @@ export interface RenderedHeader {
   hash: string;
 }
 
-/** Cache: rendered header keyed by phase + input hash for automatic invalidation */
+/** Cache: rendered header keyed by buildId + phase + input hash for automatic invalidation */
 let cachedHeader: RenderedHeader | null = null;
+let cachedBuildId: string | null = null;
 let cachedPhase: number | null = null;
 let cachedInputHash: string | null = null;
 
@@ -22,6 +23,19 @@ let cachedInputHash: string | null = null;
  * Compute a hash of the variable inputs that affect the rendered header.
  * Used to detect mid-phase mutations (e.g., ios_features changing within a phase).
  */
+/**
+ * Extract the 7 DNA axis values from DESIGN.md `## Overview > ### Brand DNA` block.
+ * The block is a bullet list of 7 axes; we capture the bullets (one per axis)
+ * and join them with newlines. Falls back to first 5 non-frontmatter lines if
+ * the block is missing (legacy/partial files).
+ */
+function extractBrandDnaBlock(content: string): string {
+  const dnaMatch = content.match(/###\s+Brand DNA\s*\n([\s\S]*?)(?=\n###\s|\n##\s|$)/);
+  if (dnaMatch) return dnaMatch[1].trim().split('\n').slice(0, 7).join('\n');
+  const stripped = content.replace(/^---\n[\s\S]*?\n---\n/, '');
+  return stripped.split('\n').slice(0, 5).join('\n').trim();
+}
+
 function inputHash(input: ContextHeaderInput): string {
   const key = JSON.stringify({
     projectType: input.projectType,
@@ -38,20 +52,27 @@ function inputHash(input: ContextHeaderInput): string {
  * Automatically invalidates if inputs change within the same phase
  * (e.g., ios_features mutating mid-build per spec pass criteria).
  */
-export function renderContextHeader(input: ContextHeaderInput): RenderedHeader {
+export function renderContextHeader(input: ContextHeaderInput, buildId: string): RenderedHeader {
   const currentInputHash = inputHash(input);
-  // Return cached if same phase AND same inputs
-  if (cachedPhase === input.phase && cachedInputHash === currentInputHash && cachedHeader) return cachedHeader;
+  // Return cached if same build, same phase, AND same inputs
+  if (
+    cachedBuildId === buildId &&
+    cachedPhase === input.phase &&
+    cachedInputHash === currentInputHash &&
+    cachedHeader
+  ) return cachedHeader;
 
   const lines: string[] = ['CONTEXT:'];
   lines.push(`  project_type: ${input.projectType}`);
   lines.push(`  phase: ${input.phase}`);
 
-  // DNA: only for web, phase >= 4
+  // DNA: only for web, phase >= 4. Extract the 7 axis values from
+  // DESIGN.md `## Overview > ### Brand DNA` h3 block — NOT the full file.
+  // Falls back to first 5 lines if the block is absent (legacy/partial files).
   if (input.projectType === 'web' && input.phase >= 4 && input.visualDnaPath) {
     if (existsSync(input.visualDnaPath)) {
-      const dna = readFileSync(input.visualDnaPath, 'utf-8');
-      const summary = dna.split('\n').slice(0, 5).join('\n').trim();
+      const content = readFileSync(input.visualDnaPath, 'utf-8');
+      const summary = extractBrandDnaBlock(content);
       lines.push(`  dna: ${summary}`);
     }
   }
@@ -72,6 +93,7 @@ export function renderContextHeader(input: ContextHeaderInput): RenderedHeader {
   const content = lines.join('\n');
   const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
 
+  cachedBuildId = buildId;
   cachedHeader = { content, hash };
   cachedPhase = input.phase;
   cachedInputHash = currentInputHash;
@@ -83,13 +105,15 @@ export function renderContextHeader(input: ContextHeaderInput): RenderedHeader {
  */
 export function invalidateCache(): void {
   cachedHeader = null;
+  cachedBuildId = null;
   cachedPhase = null;
   cachedInputHash = null;
 }
 
 /**
- * Check if the cache is valid for a given phase.
+ * Check if the cache is valid for a given build + phase.
  */
-export function isCacheValid(phase: number): boolean {
+export function isCacheValid(phase: number, buildId?: string): boolean {
+  if (buildId !== undefined && cachedBuildId !== buildId) return false;
   return cachedPhase === phase && cachedHeader !== null;
 }

package/src/orchestrator/hooks/token-accounting.ts

@@ -14,6 +14,7 @@ export interface AccountingEntry {
   step: string;
   task?: string;
   subagent_type?: string;
+  model?: string;
   usage: TokenUsage;
   cost_usd: number;
   cumulative_usd: number;
@@ -22,34 +23,41 @@ export interface AccountingEntry {
 /** Running cumulative cost across the build */
 let cumulativeCost = 0;
 
-/** Pricing per million tokens (sonnet defaults) */
-const PRICING = {
-  input: 3.0,
-  output: 15.0,
-  cache_read: 0.30,
-  cache_create: 3.75,
+/** Per-model pricing per million tokens */
+export const PRICING_TABLE: Record<string, { input: number; output: number; cache_read: number; cache_create: number }> = {
+  'claude-sonnet-4-5':  { input: 3.0,  output: 15.0, cache_read: 0.30, cache_create: 3.75 },
+  'claude-haiku-3-5':   { input: 0.80, output: 4.0,  cache_read: 0.08, cache_create: 1.00 },
+  'claude-opus-4-5':    { input: 15.0, output: 75.0, cache_read: 1.50, cache_create: 18.75 },
 };
+const DEFAULT_PRICING = PRICING_TABLE['claude-sonnet-4-5'];
 
 /**
  * Calculate cost from token usage.
+ * When `model` is omitted or unrecognised, Sonnet pricing is used.
  */
-export function calculateCost(usage: TokenUsage): number {
-  const inputCost = (usage.input_tokens / 1_000_000) * PRICING.input;
-  const outputCost = (usage.output_tokens / 1_000_000) * PRICING.output;
-  const cacheReadCost = ((usage.cache_read ?? 0) / 1_000_000) * PRICING.cache_read;
-  const cacheCreateCost = ((usage.cache_create ?? 0) / 1_000_000) * PRICING.cache_create;
+export function calculateCost(usage: TokenUsage, model?: string): number {
+  const pricing = (model ? PRICING_TABLE[model] : undefined) ?? DEFAULT_PRICING;
+  const inputCost       = (usage.input_tokens  / 1_000_000) * pricing.input;
+  const outputCost      = (usage.output_tokens / 1_000_000) * pricing.output;
+  const cacheReadCost   = ((usage.cache_read   ?? 0) / 1_000_000) * pricing.cache_read;
+  const cacheCreateCost = ((usage.cache_create ?? 0) / 1_000_000) * pricing.cache_create;
   return Math.round((inputCost + outputCost + cacheReadCost + cacheCreateCost) * 10000) / 10000;
 }
 
 /**
  * Record a token usage entry and append to build-log.md.
+ *
+ * @param startingCost — optional seed value so callers can restore
+ *   cumulative cost from a persisted build-log at build start.
+ *   Defaults to the current in-memory cumulative cost.
  */
 export function recordUsage(
   buildLogPath: string,
   entry: Omit<AccountingEntry, 'cost_usd' | 'cumulative_usd' | 'timestamp'>,
+  startingCost = cumulativeCost,
 ): AccountingEntry {
-  const cost = calculateCost(entry.usage);
-  cumulativeCost += cost;
+  const cost = calculateCost(entry.usage, entry.model);
+  cumulativeCost = startingCost + cost;
 
   const record: AccountingEntry = {
     timestamp: new Date().toISOString(),
@@ -73,6 +81,7 @@ export function formatLogLine(entry: AccountingEntry): string {
   const meta = [`phase=${entry.phase}`, `step=${entry.step}`];
   if (entry.task) meta.push(`task=${entry.task}`);
   if (entry.subagent_type) meta.push(`subagent_type=${entry.subagent_type}`);
+  if (entry.model) meta.push(`model=${entry.model}`);
 
   const tokens = [
     `input_tokens=${entry.usage.input_tokens}`,
@@ -94,7 +103,9 @@ export function getCumulativeCost(): number {
 }
 
 /**
- * Reset cumulative cost (for testing).
+ * Reset cumulative cost to zero.
+ * Call at build initialisation to prevent cross-build drift
+ * when the process is long-lived.
  */
 export function reset(): void {
   cumulativeCost = 0;

package/src/orchestrator/mcp/cycle-counter.ts

@@ -8,6 +8,7 @@
  */
 
 import type { InFlightBackwardEdge, BackwardRoutingCounters } from '../schemas/backward-edge';
+import { STALE_EDGE_THRESHOLD_MS } from '../schemas/backward-edge';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -93,7 +94,7 @@ export function clearInFlightEdge(state: CounterState): void {
  * If edge is older than threshold, decrement both counters and clear the edge.
  * Returns true if a stale edge was cleaned up.
  */
-export function handleStaleEdge(state: CounterState, thresholdMs: number = 60_000): boolean {
+export function handleStaleEdge(state: CounterState, thresholdMs: number = STALE_EDGE_THRESHOLD_MS): boolean {
   const edge = state.in_flight_backward_edge;
   if (!edge) return false;
 

package/src/orchestrator/mcp/scribe.ts

@@ -10,7 +10,7 @@
  * Migration ref: MIGRATION-PLAN-FINAL.md §4 Stage 1 (tasks 1.2.1–1.2.3)
  */
 
-import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 // ---------------------------------------------------------------------------
@@ -37,13 +37,12 @@ export interface DecisionRow {
 
 export interface ScribeInput {
   phase: string;
-  category: string;
   summary: string;
   decided_by: string;
   impact_level: 'low' | 'medium' | 'high' | 'critical';
   chosen_approach: string;
   rejected_alternatives?: RejectedAlternative[];
-  ref?: string;
+  ref: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -63,8 +62,15 @@ const MAX_REVISIT_LEN = 240;
 /** Ref field pattern from decisions.schema.json */
 const REF_PATTERN = /^[a-zA-Z0-9_\-./]+\.(md|json|jsonl|yaml|yml)(#[a-zA-Z0-9_\-/.]+)?$/;
 
-/** Phase string pattern from decisions.schema.json */
-const PHASE_PATTERN = /^[0-9]+(\.[0-9]+)?$/;
+/** Phase string pattern from decisions.schema.json. Leading minus allowed for Phase -1 (iOS bootstrap). */
+const PHASE_PATTERN = /^-?[0-9]+(\.[0-9]+)?$/;
+
+/** Encode a phase token for embedding in a decision_id. Negative phases get an "N" prefix
+ * instead of "-" to avoid colliding with the "-" delimiter in the ID format. So phase "-1"
+ * becomes "N1" in the ID slot, yielding "D-N1-01". Round-trippable via decodePhaseFromId. */
+function encodePhaseForId(phase: string): string {
+  return phase.startsWith('-') ? `N${phase.slice(1)}` : phase;
+}
 
 // ---------------------------------------------------------------------------
 // Per-phase sequence counters (task 1.2.3 — ID allocation)
@@ -96,10 +102,11 @@ export function loadCounters(filePath: string): void {
   }
 }
 
-/** Allocate the next decision ID for a phase. Format: D-{phase}-{seq} */
+/** Allocate the next decision ID for a phase. Format: D-{encodedPhase}-{seq} */
 function allocateId(phase: string): string {
-  counters[phase] = (counters[phase] ?? 0) + 1;
-  return `D-${phase}-${String(counters[phase]).padStart(2, '0')}`;
+  const encoded = encodePhaseForId(phase);
+  counters[encoded] = (counters[encoded] ?? 0) + 1;
+  return `D-${encoded}-${String(counters[encoded]).padStart(2, '0')}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,14 +186,11 @@ export function validate(input: ScribeInput): void {
   if (!input.decided_by || input.decided_by.length === 0) {
     throw new Error('decided_by is required');
   }
-  if (!input.category) {
-    throw new Error('category is required');
-  }
   if (!VALID_IMPACTS.includes(input.impact_level as typeof VALID_IMPACTS[number])) {
     throw new Error(`Invalid impact_level: ${input.impact_level}. Must be one of: ${VALID_IMPACTS.join(', ')}`);
   }
-  if (input.ref !== undefined && input.ref !== '' && !REF_PATTERN.test(input.ref)) {
-    throw new Error(`Invalid ref: "${input.ref}". Must match pattern ${REF_PATTERN.source}`);
+  if (!input.ref || input.ref.length === 0 || !REF_PATTERN.test(input.ref)) {
+    throw new Error(`Invalid ref: "${input.ref ?? ''}". Must match pattern ${REF_PATTERN.source}`);
   }
 
   const alts = input.rejected_alternatives ?? [];
@@ -221,6 +225,9 @@ export function scribeDecision(input: ScribeInput, filePath: string): DecisionRo
   try {
     validate(input);
 
+    // Auto-rehydrate counters from disk (idempotent — takes max per phase)
+    loadCounters(filePath);
+
     // Enforce max 5 rows per phase
     const existing = countPhaseRows(filePath, input.phase);
     if (existing >= MAX_ROWS_PER_PHASE) {
@@ -238,7 +245,7 @@ export function scribeDecision(input: ScribeInput, filePath: string): DecisionRo
       chosen_approach: input.chosen_approach,
       rejected_alternatives: input.rejected_alternatives ?? [],
       decided_by: input.decided_by,
-      ref: input.ref ?? '',
+      ref: input.ref,
       status: 'open',
     };
 
@@ -248,8 +255,12 @@ export function scribeDecision(input: ScribeInput, filePath: string): DecisionRo
       mkdirSync(dir, { recursive: true });
     }
 
-    // Append-only write — NEVER rewrite or truncate
-    writeFileSync(filePath, JSON.stringify(row) + '\n', { flag: 'a' });
+    // ATOMIC: read existing + append new row + write-to-tmp + rename
+    const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const newContent = existingContent + JSON.stringify(row) + '\n';
+    const tmp = `${filePath}.tmp`;
+    writeFileSync(tmp, newContent, 'utf-8');
+    renameSync(tmp, filePath); // atomic on POSIX same-filesystem
 
     return row;
   } finally {

package/src/orchestrator/mcp/write-lease.ts

@@ -91,25 +91,42 @@ function persistLeases(): void {
   }
 }
 
+/**
+ * Process-level async mutex for acquireWriteLease.
+ *
+ * Serializes all callers through a promise chain so that even if two async
+ * dispatch paths call acquireWriteLease concurrently, the overlap check and
+ * push are never interleaved. This prevents a TOCTOU race where both callers
+ * read the leases array before either persists, granting conflicting leases.
+ */
+let acquireLock: Promise<void> = Promise.resolve();
+
 /**
  * Acquire a write lease for the given file paths.
  * Persists to disk atomically so the PreToolUse hook sees the lease.
+ *
+ * Serialized via an async mutex (promise chain) to prevent TOCTOU races
+ * when called from concurrent async dispatch paths.
  */
-export function acquireWriteLease(taskId: string, filePaths: string[]): AcquireResult {
-  if (!taskId) throw new Error('task_id is required');
-  if (!filePaths.length) throw new Error('file_paths must be non-empty');
-
-  for (const existing of leases) {
-    const overlap = filePaths.filter(p => existing.paths.includes(p));
-    if (overlap.length > 0) {
-      return { granted: false, conflict: { holder: existing.holder, paths: overlap } };
+export async function acquireWriteLease(taskId: string, filePaths: string[]): Promise<AcquireResult> {
+  const result = acquireLock.then(() => {
+    if (!taskId) throw new Error('task_id is required');
+    if (!filePaths.length) throw new Error('file_paths must be non-empty');
+
+    for (const existing of leases) {
+      const overlap = filePaths.filter(p => existing.paths.includes(p));
+      if (overlap.length > 0) {
+        return { granted: false, conflict: { holder: existing.holder, paths: overlap } };
+      }
     }
-  }
 
-  const lease: Lease = { holder: taskId, paths: [...filePaths], acquired_at: new Date().toISOString() };
-  leases.push(lease);
-  persistLeases();
-  return { granted: true, lease };
+    const lease: Lease = { holder: taskId, paths: [...filePaths], acquired_at: new Date().toISOString() };
+    leases.push(lease);
+    persistLeases();
+    return { granted: true, lease };
+  });
+  acquireLock = result.then(() => {}, () => {}); // advance chain regardless of success/failure
+  return result;
 }
 
 /**

package/src/orchestrator/phase4-shared-context.ts

@@ -31,11 +31,27 @@ export function renderSprintContext(input: SprintContextInput): SprintContextBlo
   return { content, hash };
 }
 
+/**
+ * Hash only the inputs that affect rendered output (excludes buildState).
+ * Cheaper than a full renderSprintContext — no section joins or content hashing.
+ * Callers should store this hash and pass it to shouldInvalidate.
+ */
+export function inputHash(input: SprintContextInput): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      architecture: input.architecture,
+      qualityTargets: input.qualityTargets,
+      refs: input.refs,
+      iosFeatures: input.iosFeatures ?? null,
+    }))
+    .digest('hex')
+    .slice(0, 16);
+}
+
 /**
  * Check if the sprint context needs re-rendering (hash invalidation).
- * Returns true if refs have changed since last render.
+ * Compares input hashes directly — avoids a full render just to get a hash.
  */
-export function shouldInvalidate(currentHash: string, newInput: SprintContextInput): boolean {
-  const newBlock = renderSprintContext(newInput);
-  return newBlock.hash !== currentHash;
+export function shouldInvalidate(currentInputHash: string, newInput: SprintContextInput): boolean {
+  return inputHash(newInput) !== currentInputHash;
 }

package/protocols/visual-dna.md

@@ -1,185 +0,0 @@
-# Visual DNA Protocol
-
-Phase 3.0 Brand Guardian locks a 7-axis Visual DNA card that becomes the single source of truth for every downstream Phase 3 design step and every Phase 4 implementer that touches visual output. Visual Research (3.1), Visual Designer (3.2, 3.4), UX Architect (3.3), Inclusive Visuals Specialist (3.5), Frontend Developer generator (3.6), Design Critic (3.6), Accessibility Auditor (3.7), and every Phase 4 implementer via `refs.json` read this card before producing any visual artifact. It is the most load-bearing artifact in the visual pipeline — if the DNA drifts, every downstream surface drifts with it. This protocol exists to make the schema, ownership, and legal-combination rules explicit.
-
-## 1. The 7 axes
-
-Each axis has a closed value set. Brand Guardian picks one value per axis at Phase 3.0 and never revises it mid-build (a DNA revision is a new build session).
-
-### Scope
-
-**Values:** Marketing / Product / Dashboard / Internal Tool
-
-Scope is the **gating axis**. It decides which libraries get vendored into the Phase 4 scaffold and sets the per-page bundle budget enforced by the Phase 6 SRE chapter. Three.js/WebGL libraries install only for Marketing or Product-with-Expressive-motion; dashboards and internal tools never ship them. Perf budgets: Marketing 500KB, Product 300KB, Dashboard 400KB, Internal Tool 200KB (gzipped, excluding images). Exceeding budget by >25% auto-blocks the LRR SRE chapter.
-
-### Density
-
-**Values:** Airy / Balanced / Dense
-
-Density controls the spacing scale, type size ramp, whitespace rhythm, and information-per-viewport target. Airy is marketing-friendly breathing room; Dense is power-user tool territory (Linear, Superhuman, Datadog consoles). The Visual Designer at 3.4 maps this to concrete Tailwind spacing tokens and line-height ramps.
-
-### Character
-
-**Values:** Minimal / Editorial / Maximalist / Brutalist / Playful
-
-Character is the overall visual personality. It drives typographic choice, color saturation, decoration rules, and the general "what kind of product is this" read within 200ms of page load. Minimal is Stripe-adjacent. Editorial is magazine-like with strong type hierarchy. Maximalist is decoration-heavy (aceternity/ui territory). Brutalist is raw and aggressive. Playful is rounded, animated, approachable.
-
-### Material
-
-**Values:** Flat / Glassy / Physical / Neumorphic
-
-Material is the surface treatment across every card, modal, button, and panel. It determines blur radii, border styles, elevation system, and shadow character. Flat is modern shadcn default. Glassy is backdrop-filter blur + subtle borders (Apple / Vercel aesthetic). Physical is realistic drop shadows and depth. Neumorphic is soft inset/outset shadows (fragile — breaks contrast easily).
-
-### Motion
-
-**Values:** Still / Subtle / Expressive / Cinematic
-
-Motion drives easing curves, animation durations, scroll choreography, hover feedback, and page transitions. Still is no motion. Subtle is shadcn-default hover transitions (150-200ms ease-out). Expressive is framer-motion choreography with spring physics. Cinematic is GSAP + ScrollTrigger with 500-800ms eases — the Neuform / aura.build kind of motion that requires heavy libraries and is bundle-expensive.
-
-### Type
-
-**Values:** Neutral Sans / Humanist Sans / Serif-forward / Display-forward / Mono-accented
-
-Type is the font-pairing strategy. It controls primary/secondary font choice, tracking rules, and optical sizing decisions. Neutral Sans is Inter / Geist (safe default). Humanist Sans is Söhne / Söhne Breit (warmer). Serif-forward is Tiempos / GT Super (editorial feel). Display-forward is a bold display face paired with a neutral body. Mono-accented uses JetBrains Mono / IBM Plex Mono for labels and callouts inside an otherwise-sans design. Specific font pairings live in `docs/library-refs/component-library-catalog.md`, not here.
-
-### Copy
-
-**Values:** Functional / Narrative / Punchy / Technical
-
-Copy is the language register across headlines, CTAs, labels, and microcopy. It controls vocabulary density, sentence rhythm, and the emotional distance between product and user. Functional is labels-only, no sales language — content-first (Notion, Linear dashboard). Narrative uses scene-setting and emotional pull — headlines paint a moment (Stripe, Loom). Punchy enforces 3-5 word headlines, one idea per sentence, newspaper economy — cut half, then cut again (Arc, Raycast). Technical uses precise terminology, spec-like voice, avoids marketing softeners — values exactness over warmth (Vercel, Railway).
-
-## 2. Incompatibility matrix
-
-<HARD-GATE>
-Brand Guardian is forbidden from locking any of the combinations below. If the user's references or design doc push toward an illegal combo, Brand Guardian picks the closest legal alternative and emits a decision-log row explaining the rejection.
-</HARD-GATE>
-
-| # | Illegal combination | Why |
-|---|---|---|
-| 1 | Dashboard + Cinematic motion | Dashboards need snappy feedback (100-200ms), not 650ms cinematic eases. Users lose their place. |
-| 2 | Internal Tool + Maximalist character | Internal tools exist for fast parse; decoration-heavy styling buries the data users came for. |
-| 3 | Internal Tool + Expressive or Cinematic motion | Internal tools ship at <200KB budget; framer-motion choreography + GSAP break that budget. |
-| 4 | Marketing + Dense density | Marketing pages need breathing room to sell; dense kills scroll rhythm and conversion. |
-| 5 | Dashboard + Glassy material + Dense density | Glass blur on dense data surfaces renders unreadable — the backdrop-filter eats legibility. |
-| 6 | Dashboard + Serif-forward type | Dashboards need high-readability UI faces at small sizes; serifs lose clarity at 12-14px. |
-| 7 | Product + Neumorphic material (with WCAG AA target) | Neumorphic shadows depend on low-contrast surfaces; AA contrast math fails by construction. |
-| 8 | Brutalist character + Glassy material | Brutalism is raw, unapologetic, unadorned; glass is the opposite ethos. Visual contradiction. |
-| 9 | Playful character + Still motion | Playful without motion reads as stiff and off-brand. Playful implies at least Subtle motion. |
-| 10 | Marketing + Still motion | Marketing pages rely on scroll reveal and choreography to guide attention; Still kills that. |
-| 11 | Internal Tool + Display-forward type | Display faces are for hero moments, not tool chrome. Clashes with fast-parse requirement. |
-| 12 | Dashboard + Physical material | Heavy drop shadows on data grids add visual noise that competes with the chart ink. |
-| 13 | Playful character + Technical copy | Playful implies approachable warmth; technical copy creates cognitive dissonance — the visual feel promises friendliness, the words deliver distance. |
-| 14 | Brutalist character + Narrative copy | Brutalism is raw, direct, unapologetic; narrative copy is storytelling and emotional pull — the aesthetic actively rejects the storytelling register. |
-
-Anything not on this list is legal. When two legal combinations both fit the user's references, Brand Guardian reads `quality-targets.json` and the architecture stack to resolve ties (e.g., if the stack is Next.js + shadcn default and quality-targets say "fast MVP," prefer Flat over Glassy).
-
-## 3. Schema
-
-The DNA card lives at `docs/plans/visual-dna.md` — one file per build, locked at Phase 3.0. Shape:
-
-```markdown
----
-locked_at: 2026-04-14T01:23:45Z
-locked_by: Brand Guardian
-build_session: <session_id>
----
-
-# Visual DNA
-
-## Axes
-
-- Scope: Marketing
-- Density: Airy
-- Character: Editorial
-- Material: Glassy
-- Motion: Expressive
-- Type: Display-forward
-- Copy: Punchy
-
-## Rationale
-
-<why these axes, with explicit references to design-doc.md sections and findings-digest signals
-that pushed each axis to the chosen value; 4-8 sentences total, no padding>
-
-## References that exemplify this DNA
-
-- <url or path> — exemplifies Character + Motion
-- <url or path> — exemplifies Material + Type
-- <url or path> — exemplifies Scope + Density
-```
-
-<HARD-GATE>
-SCHEMA CONTRACT:
-
-- All seven axis fields MUST be present and MUST be one of the allowed values from Section 1.
-- The combination across all six axes MUST NOT appear in the Section 2 incompatibility matrix.
-- `locked_at` is set exactly once, at Phase 3.0 Brand Guardian completion, and is never rewritten.
-- `References that exemplify this DNA` MUST contain at least two entries, each tied to specific axis pairs. "Looks good" without axis attribution is not permitted.
-- Only `docs/plans/visual-dna.md` is the canonical location. No other path is read.
-</HARD-GATE>
-
-## 4. Ownership
-
-**Writer:** Brand Guardian at Phase 3.0, exactly once per build. No other agent writes `visual-dna.md`. If the user requests a DNA revision mid-build, that is a new Phase 3.0 invocation, not an edit.
-
-**Readers:**
-
-| Phase / Step | Agent | Why it reads DNA |
-|---|---|---|
-| 3.1 | Visual Research | Frames reference-site lookup queries around the locked axes instead of casting wide. |
-| 3.2 | Visual Designer (Component Library Mapping) | Picks component variants from `component-library-catalog.md` matching the DNA axis combination. |
-| 3.3 | UX Architect | Information architecture and flow choices respect Density and Character. |
-| 3.4 | Visual Designer (Visual Design Spec) | Material system, motion system, and typographic tuning all derive from Material/Motion/Type axes. |
-| 3.5 | Inclusive Visuals Specialist | Checks DNA for a11y risks (Neumorphic contrast, Dense density tap targets, Cinematic motion reduced-motion fallback). |
-| 3.6 | Frontend Developer generator | Every generated surface honors DNA; deviations flagged by Design Critic. |
-| 3.6 | Design Critic | Scores rendered output against DNA on all seven axes + craft dimensions in the metric loop. |
-| 3.7 | Accessibility Auditor | Re-verifies DNA-level a11y claims from 3.5 against real rendered output. |
-| 4 | Phase 4 implementers | Read via `refs.json` primary anchor; every component they write must match DNA or compose from the DNA-matching library variants. |
-| 5 | Drift check | Verifies visual output still reads as the locked DNA. |
-| 6 | Brand Guardian chapter | Final verdict pass against DNA as ground truth. |
-
-## 5. Legal-combo examples
-
-**Premium marketing landing page — Stripe / Linear / Neuform aesthetic:**
-
-- Scope: Marketing
-- Density: Airy
-- Character: Editorial
-- Material: Glassy
-- Motion: Expressive
-- Type: Display-forward
-- Copy: Punchy
-
-Airy density + Editorial character gives the breathing room and strong type hierarchy. Glassy material + Display-forward type hits the premium feel. Expressive motion is the bundle budget ceiling Marketing scope can afford without tipping into Cinematic territory. Punchy copy matches the premium marketing register — short, declarative headlines that let the type and motion carry the emotional weight. All seven axes reinforce the same read.
-
-**Internal analytics dashboard — Datadog / Grafana aesthetic:**
-
-- Scope: Dashboard
-- Density: Balanced
-- Character: Minimal
-- Material: Flat
-- Motion: Subtle
-- Type: Humanist Sans
-- Copy: Functional
-
-Minimal character + Flat material + Humanist Sans is the "tool chrome that disappears" combination. Subtle motion keeps interactions snappy without distracting from the data. Balanced density fits dashboard chart density without triggering the Glassy + Dense incompatibility. Functional copy keeps labels terse and data-first — no marketing softeners competing with the charts for attention. Ships well under the 400KB Dashboard budget.
-
-**Consumer productivity app — Notion / Superhuman aesthetic:**
-
-- Scope: Product
-- Density: Balanced
-- Character: Minimal
-- Material: Physical
-- Motion: Expressive
-- Type: Neutral Sans
-- Copy: Functional
-
-Minimal + Neutral Sans is the "content is the hero" base. Physical material adds just enough depth to make interactive surfaces feel tactile. Expressive motion is where Superhuman-style transitions live. Functional copy keeps the interface out of the way of the user's content — the app labels actions, it doesn't narrate them. Product scope allows the motion library cost, since it's inside the 300KB budget when managed carefully.
-
-## 6. Illegal-combo example
-
-**Dashboard + Maximalist + Cinematic — rejected.**
-
-Three conflicts at once. Dashboards need parse-speed, which Maximalist actively fights by burying data under decoration. Cinematic motion (650ms+ eases) is too slow for the interaction rhythm dashboards require — a user filtering a table cannot wait 800ms for every state change. And the combined library cost of aceternity-heavy maximalist surfaces + GSAP cinematic motion blows the 400KB Dashboard budget on its own before any app code is added.
-
-When the user's references push toward this combination (e.g., "I want it to feel like [Neuform marketing page] but it's actually a dashboard"), Brand Guardian rejects the combination, writes a decision-log row naming the incompatibility, and asks the user to pick a direction: keep the scope and drop the Maximalist/Cinematic, or change the product scope to Marketing (which will change the whole app's shape, not just its look). There is no middle ground — the axes are load-bearing, not decorative.