@hegemonart/get-design-done 1.19.0 → 1.19.6

package/reference/emotional-design.md

@@ -0,0 +1,124 @@
+# Emotional Design — Norman's Three Levels
+
+Source: Don Norman, *Emotional Design: Why We Love (or Hate) Everyday Things* (2004). See also: `jnd.org`.
+
+Use this file as a **cross-cutting scoring lens** in design audits and reflections. The three levels apply simultaneously to every design decision — they are not sequential stages.
+
+---
+
+## The Three Levels
+
+### Visceral Level
+
+> The immediate, pre-cognitive, automatic reaction to sensory input.
+
+The visceral level operates before the user thinks. It is driven by appearance, proportion, colour, texture — the aesthetic surface. A user who says "I don't know why, but this feels cheap" is responding at the visceral level.
+
+**What it governs:**
+- First impression within 50ms of page load (aesthetic-usability effect)
+- Color palettes and their emotional valence
+- Typography weight, roundness, and whitespace generosity
+- Illustration style, photography tone, iconography personality
+- Whether motion feels fluid or mechanical
+
+**Audit signals:**
+- Does the visual system convey the intended emotional register within 3 seconds?
+- Are there conflicting visceral signals? (e.g., playful illustration + harsh red error banners)
+- Does the `style-vocabulary.md` aesthetic type match the product's emotional promise?
+
+**Scoring rubric (visceral):**
+
+| Score | Evidence |
+|---|---|
+| 4 | Emotional register clear within 3s; no conflicting signals; references a named design authority |
+| 3 | Clear emotional intent; 1–2 minor conflicts (e.g., one off-brand icon) |
+| 2 | Ambiguous emotional register; mixed signals across surfaces |
+| 1 | No discernible emotional intent; generic or template appearance |
+
+---
+
+### Behavioral Level
+
+> The experience of use — whether actions feel controllable, predictable, and rewarding.
+
+The behavioral level is what UX heuristics primarily address. It covers usability, feedback, error recovery, and responsiveness. A user who says "This is frustrating to use" is responding at the behavioral level.
+
+**What it governs:**
+- Interaction feedback (loading states, error messages, success confirmations)
+- Control and reversibility (undo, cancel, back navigation)
+- Response latency — the Doherty Threshold: feedback within 400ms
+- Error prevention and recovery
+- Learnability and consistency across screens
+
+**Audit signals:**
+- Can the user always tell what the system is doing? (H-01 Visibility)
+- Are errors expressed as human problems with solutions? (H-09 Error Recovery)
+- Is every action reversible within 5 seconds?
+- Does the system respond within 400ms (Doherty Threshold)?
+
+**Scoring rubric (behavioral):**
+
+| Score | Evidence |
+|---|---|
+| 4 | All states visible; errors human + actionable; Doherty Threshold met; all destructive actions reversible |
+| 3 | Most states covered; 1–2 feedback gaps that don't block task completion |
+| 2 | Notable feedback gaps; some irreversible actions without warning |
+| 1 | System status invisible; errors developer-facing; no undo for destructive actions |
+
+---
+
+### Reflective Level
+
+> The conscious, post-use evaluation — meaning, narrative, and self-image.
+
+The reflective level is where brand identity, storytelling, and pride of ownership live. A user who says "I love showing this tool to colleagues" is responding at the reflective level. This level takes the longest to build and the longest to repair when damaged.
+
+**What it governs:**
+- Whether the product aligns with the user's self-image
+- Brand narrative consistency across all touchpoints
+- Delight and surprise moments — not gimmicks; earned moments
+- The **Peak** moment in the Peak-End Rule: the highest positive moment in the flow
+- Long-term loyalty and word-of-mouth referral
+
+**Audit signals:**
+- Is there an identifiable "peak" moment in the primary user flow?
+- Does the brand voice (from `brand-voice.md`) carry through to microcopy and empty states?
+- Is there a designed completion state that communicates personality?
+- Does the product give users a story to tell? (e.g., a completion screen, an achievement, a shareable output)
+
+**Scoring rubric (reflective):**
+
+| Score | Evidence |
+|---|---|
+| 4 | Identifiable designed peak moment; brand voice consistent from entry to completion; users have a story to tell |
+| 3 | Brand voice present in most surfaces; peak moment implicit but not deliberately designed |
+| 2 | Brand voice inconsistent; no designed peak; product is functional but forgettable |
+| 1 | Generic experience; no emotional arc; could be any product in the category |
+
+---
+
+## Cross-Cutting Lens Application
+
+Apply this lens as a **secondary overlay** after scoring the primary audit pillars. For each of the three levels:
+
+1. Identify 1–2 evidence items from the primary audit (e.g., Pillar 3 Color → Visceral Level)
+2. Note conflicts between levels (e.g., Behavioral score 4 but Visceral score 1 = technically functional but aesthetically repellent)
+3. Flag the weakest level as the highest-leverage improvement opportunity
+
+**Common cross-level conflict patterns:**
+
+| Conflict pattern | Diagnosis | Remedy |
+|---|---|---|
+| High behavioral, low visceral | Technically usable but aesthetically generic | Audit against `style-vocabulary.md`; commit to a stronger aesthetic type |
+| High visceral, low behavioral | Beautiful but broken | Fix H-01, H-09 violations first — UX before aesthetics |
+| High visceral + behavioral, low reflective | Polished but forgettable | Design a peak moment; review `brand-voice.md` emotional arc |
+
+---
+
+## Wiring
+
+**design-auditor:** After pillar scoring, apply emotional-design lens as a cross-cutting overlay. Add `## Emotional Design Overlay` section to `DESIGN-AUDIT.md` with scores for all three levels and any cross-level conflict notes.
+
+**design-reflector:** In Section 1 (What Surprised Us), flag if visceral vs behavioral scores diverge by ≥2 points — this is a leading indicator of the "beautiful but broken" pattern.
+
+**design-discussant:** In `--spec` mode, include one reflective-level confidence-scored question: "What story does this product help the user tell about themselves?"

package/reference/first-principles.md

@@ -0,0 +1,89 @@
+# First Principles — Invariant Design Constraints
+
+> These are the three invariants that no design decision can override. They are facts about human biology and cognition, not preferences or conventions. Every design choice is downstream of these three constraints.
+
+Use during the brief/discover stage (`design-discussant`) as a sanity check: does the proposed direction respect all three invariants? Use during verify as a reducibility check: can each element be removed without breaking the user's ability to complete their goal?
+
+---
+
+## Invariant 1: Body
+
+The user has a physical body with physiological limits. No amount of design skill overrides human motor physiology.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Touch targets must accommodate tremor and fat-finger error | `min-h-[44px] min-w-[44px]` on all interactive elements |
+| Precision degrades with distance (Fitts's Law) | Destructive actions separated from primary actions by ≥24px or significantly smaller |
+| Scroll fatigue is real | Sticky headers + back-to-top anchor for content > 3 viewport heights |
+| Physical feedback confirms action | `scale(0.96)` press feedback on all clickable surfaces |
+| Eye strain limits reading distance | Body text ≥16px; line-length 60–75ch |
+
+**Reducibility check:** Can the user complete this task without a mouse? Without a precise pointer? On a 4-inch screen in a moving vehicle?
+
+---
+
+## Invariant 2: Attention
+
+Attention is finite and non-renewable per unit of time. Every element on screen competes for the same fixed budget.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Attention capacity: 5–9 items (Miller's Law) | Navigation: ≤7 top-level items; dropdown > 7 items gets search |
+| Decision cost grows with choice count (Hick's Law) | Pricing: ≤3 tiers; feature lists: ≤4 items per group |
+| One primary action per screen | Single `.btn-primary` per viewport; all others `.btn-secondary` or `.btn-ghost` |
+| Animation hijacks attention | Motion only on state change; no decorative looping animations |
+| Progressive disclosure reduces overload | Advanced options behind disclosure trigger, not visible by default |
+
+**Reducibility check:** If you removed 30% of the elements on this screen, would task completion rate drop? If not, remove them.
+
+---
+
+## Invariant 3: Memory
+
+Working memory holds approximately 7 items and degrades rapidly within seconds. Design that requires users to remember things between screens fails.
+
+**Principle → Code pairs:**
+
+| Principle | Code Pattern |
+|---|---|
+| Recognition over recall (H-06) | Visible navigation labels, not icon-only; breadcrumbs on deep paths |
+| Context must be preserved | Multi-step forms: prior-step summary visible; form state not cleared on back-navigate |
+| Error memory fades fast | Inline validation: errors adjacent to the field that caused them |
+| Completion status reduces anxiety | Progress indicators: `Step 2 of 4`; Zeigarnik Effect — show percentage done |
+| Last action should be reversible | Undo available for destructive/irreversible actions within 5 seconds |
+
+**Reducibility check:** Does this screen require the user to remember something from a previous screen? If yes, surface that context inline.
+
+---
+
+## The Reducibility Test
+
+For any proposed design element, apply in order:
+
+1. **Body test** — Is this element reachable by a person with limited motor precision on a small screen?
+2. **Attention test** — Does this element earn its place by directly supporting the primary task?
+3. **Memory test** — Does this element surface context the user would otherwise need to remember?
+
+If an element fails all three tests, it is purely decorative. Decorative elements are not forbidden — but they are not invariant-justified, and they are the first candidates for removal when performance or clarity is at risk.
+
+---
+
+## Wiring to Design Discussant
+
+When `design-discussant` runs the brief stage, it prepends this invariants question before the main interview:
+
+> "Before we discuss the design direction, let me confirm three constraints: (1) Are there any accessibility requirements for motor-impaired users? (2) Is the primary use case on mobile or desktop — or both? (3) Are there any multi-step flows where the user must carry context between screens?"
+
+Answers are recorded as D-XX decisions prefixed `[Invariant]` in STATE.md.
+
+---
+
+## Relationship to Other References
+
+- `reference/heuristics.md` — H-01 through H-10 are the behavioral-level expression of Invariants 2 and 3
+- `reference/emotional-design.md` — Invariant 1 (Body) maps to the Visceral level; Invariants 2–3 map to the Behavioral level
+- `reference/component-authoring.md` — P-01 through P-06 are the component-level expression of all three invariants

package/reference/heuristics.md

@@ -181,6 +181,76 @@ People **remember incomplete tasks** better than completed ones. Implications:
 
 ---
 
+## Peak-End Rule
+
+Users judge an experience primarily by how it felt at its most intense moment (the **peak**) and how it ended — not by the average across the whole session. Implications:
+- Design a deliberate positive peak in every primary flow (e.g., a celebratory completion screen, an instant result, a delightful empty state).
+- The **end state** of a flow matters disproportionately: the last screen the user sees shapes their memory of the whole interaction.
+- Reduce negative peaks first (error states, loading hangs) — they weigh heavier than neutral moments.
+- A long frustrating form followed by a satisfying completion screen is remembered more positively than a mildly annoying end to an otherwise smooth flow.
+
+---
+
+## Loss Aversion
+
+Users feel the pain of loss approximately **twice as strongly** as the pleasure of an equivalent gain (Kahneman & Tversky). Implications:
+- Frame CTAs around what users keep/save, not what they gain: "Don't lose your progress" over "Save your work."
+- Subscription cancellation flows that show what the user will lose (features, data, streak) leverage loss aversion ethically to reduce churn — but only if the stated losses are real.
+- Free trial countdowns ("3 days left") trigger loss aversion more effectively than benefit reminders.
+- Destructive action confirmations should name what is lost: "Delete this project and all 47 files?" not just "Are you sure?"
+
+---
+
+## Cognitive Load Theory
+
+Working memory is limited to approximately **7 ± 2 chunks** simultaneously (Miller, 1956) and degrades under conditions of stress, distraction, or novelty. Cognitive Load Theory (Sweller, 1988) distinguishes three types:
+
+| Type | Definition | Design implication |
+|---|---|---|
+| **Intrinsic** | Load inherent to the task itself (complexity of the domain) | Cannot be reduced; must be scaffolded |
+| **Extraneous** | Load imposed by poor design (navigation, unclear labels, visual noise) | Eliminate this completely |
+| **Germane** | Load that builds understanding (learning, pattern recognition) | Preserve and support |
+
+Practical rules:
+- Every element of visual noise is extraneous load — remove it.
+- New UI patterns create extraneous load (Jakob's Law); use platform conventions.
+- Chunk complex tasks into steps of ≤3 decisions each.
+- Error messages that require decoding ("Error 422") create extraneous load; plain language removes it.
+
+---
+
+## Aesthetic-Usability Effect
+
+Users perceive **aesthetically pleasing designs as more usable**, even when functionality is identical — and this perception persists through initial usability problems. Implications:
+- A polished visual appearance buys tolerance for minor UX rough edges in early releases.
+- This effect is strongest on first impression; it degrades over time as behavioral friction compounds.
+- The effect can mask genuine usability problems in user testing if participants rate overall satisfaction rather than task completion.
+- Do NOT use the aesthetic-usability effect as a reason to defer fixing usability problems — it explains tolerance, not satisfaction.
+
+---
+
+## Doherty Threshold
+
+A system that responds within **400ms** keeps users in a state of flow. Response times above 400ms cause users to shift attention, leading to a productivity drop that compounds with task complexity. Named after W.J. Doherty and R.H. Thadhani (IBM, 1982). Implications:
+- Interactive responses (button click → visible feedback) must be ≤400ms.
+- For operations > 400ms, show optimistic UI immediately and settle in the background.
+- For operations > 1000ms, use a progress indicator.
+- For operations > 10s, provide a way to continue other tasks (async notification on complete).
+- Loading spinners that appear within 400ms reduce perceived wait; those that appear late increase it.
+
+---
+
+## Flow (Csikszentmihalyi)
+
+Users enter a **flow state** when task difficulty matches their skill level exactly — high enough to engage, low enough to feel achievable. Flow is characterized by complete absorption, loss of time awareness, and intrinsic motivation. Implications:
+- Progressive difficulty: onboarding tasks should be trivially easy; expert tasks should provide just enough challenge.
+- Interruptions break flow permanently for that session; avoid modal interruptions in high-focus workflows.
+- Clear goals + immediate feedback are the two design levers for inducing flow (H-01, H-05).
+- Forms designed for flow: one question per screen, immediate validation, visible progress.
+- Notification design: distinguish ambient notifications (don't break flow) from critical interruptions (must break flow).
+
+---
+
 ## How to Score During Verification
 
 For each NNG heuristic (H-01 through H-10), rate 0–4:

package/reference/motion-advanced.md

@@ -746,9 +746,198 @@ Fresh eyes catch what in-the-moment iteration misses. Animations feel correct wh
 
 ## Disney's 12 Principles — UX Mapping
 
-<!-- STUB: Disney's 12 Principles UX mapping — Phase 19.6 will author this section -->
-<!-- Cross-reference: reference/motion-easings.md, reference/motion-spring.md -->
+Original source: Frank Thomas & Ollie Johnston, *The Illusion of Life: Disney Animation* (1981). The 12 principles were developed for hand-drawn character animation; the UX mappings below translate each to interface motion.
 
-*This section is reserved for Phase 19.6 (Design Philosophy Layer). A full UX mapping of all 12 principles will be authored there and this stub will be replaced.*
+---
+
+### 1. Squash and Stretch
+
+**Animation:** Objects deform under force — squash on impact, stretch during fast movement.
+
+**UX mapping:** Scale feedback communicates physical weight and responsiveness.
+```tsx
+// Press: squash slightly (wider, shorter)
+// Release: snap back through scale(1.05) → scale(1)
+<motion.button
+  whileTap={{ scaleX: 1.05, scaleY: 0.95 }}
+  transition={{ type: "spring", stiffness: 500, damping: 30 }}
+/>
+```
+**Rule:** Constrain squash/stretch to ≤5% deviation — more reads as glitchy, not physical.
+
+---
+
+### 2. Anticipation
+
+**Animation:** A small preparatory motion before the main action (e.g., a character bending knees before jumping).
+
+**UX mapping:** Preview animations prime the user for what's about to happen.
+```tsx
+// Drawer that "breathes" slightly before opening
+<motion.div
+  animate={isOpen ? { x: 0 } : { x: -8 }}
+  initial={{ x: -8 }}
+  transition={{ type: "spring", stiffness: 300, damping: 24 }}
+/>
+```
+**Rule:** Anticipation delays should be ≤80ms; longer delays read as lag, not anticipation.
+
+---
+
+### 3. Staging
+
+**Animation:** Present one idea at a time; the primary action draws the eye; secondary elements are subordinate.
+
+**UX mapping:** One primary motion per state change. All other motion is either absent or staggered to follow.
+- Never animate two elements of equal visual weight simultaneously
+- Use stagger to create a reading order for entering content
+- The element the user acted on should move first
+
+---
+
+### 4. Straight Ahead vs Pose to Pose
+
+**Animation:** Straight-ahead: draw each frame in sequence. Pose-to-pose: define key positions and interpolate.
+
+**UX mapping:** All CSS transitions and spring animations are pose-to-pose by definition — you define start and end states. This means:
+- Transitions retarget smoothly when interrupted (see CSS Transitions vs Keyframes section above)
+- The in-between frames are computed by the engine, not designed
+- Design the **poses** (states) carefully; the interpolation handles itself
+
+---
+
+### 5. Follow Through and Overlapping Action
+
+**Animation:** Parts of an object continue moving after the main action stops; related elements finish at slightly different times.
+
+**UX mapping:** Stagger exit animations and let secondary elements settle slightly after primary.
+```tsx
+// List exit: items stagger out with slight delay between each
+const container = {
+  exit: { transition: { staggerChildren: 0.04, staggerDirection: -1 } },
+};
+const item = {
+  exit: { opacity: 0, y: -8, transition: { duration: 0.2 } },
+};
+```
+**Rule:** Follow-through delay ≤60ms per level. Beyond this, the UI feels sluggish.
+
+---
+
+### 6. Slow In and Slow Out
+
+**Animation:** Objects accelerate from rest and decelerate to a stop; they are never at constant velocity.
+
+**UX mapping:** Never use `linear` easing for UI transitions. Always use a curve that starts slow, speeds up, and decelerates.
+```css
+/* The standard Material/web ease — correct for most UI */
+transition: transform 0.24s cubic-bezier(0.4, 0, 0.2, 1);
+
+/* Enter (slow in) */
+transition: transform 0.24s cubic-bezier(0, 0, 0.2, 1);
+
+/* Exit (slow out) */
+transition: transform 0.2s cubic-bezier(0.4, 0, 1, 1);
+```
+**Rule:** `linear` easing is only valid for: scroll-driven animations tied to position, and progress bar fills.
+
+---
+
+### 7. Arcs
+
+**Animation:** Objects in the real world move in slight arcs, not straight lines.
+
+**UX mapping:** For spatial transitions (element moving from one position to another), a slight arc feels more natural than a straight-line translate. Achieved by animating both axes with slightly different timing:
+```tsx
+<motion.div
+  initial={{ x: -40, y: 10, opacity: 0 }}
+  animate={{ x: 0, y: 0, opacity: 1 }}
+  transition={{
+    x: { type: "spring", stiffness: 300, damping: 28 },
+    y: { type: "spring", stiffness: 300, damping: 28, delay: 0.04 },
+    opacity: { duration: 0.2 },
+  }}
+/>
+```
+**Rule:** Arcs apply only to spatial motion. Opacity, scale, and color changes do not arc.
+
+---
+
+### 8. Secondary Action
+
+**Animation:** A supporting action that reinforces the primary one (e.g., a character's hair bouncing while they walk).
+
+**UX mapping:** A small supplementary animation that confirms and amplifies the main interaction.
+- Toast notification: icon pulses briefly after the toast appears (secondary action confirming the event)
+- Success state: checkmark draws itself after the confirmation color appears
+- Delete: item fades + the list count badge decrements with a small number-flip animation
+
+**Rule:** Secondary actions must complete before or simultaneously with the primary — never after. They reinforce, not extend.
+
+---
+
+### 9. Timing
+
+**Animation:** Duration communicates physical weight. Fast = light and snappy. Slow = heavy and significant.
+
+**UX mapping:**
+
+| Duration | Use for |
+|---|---|
+| 80–120ms | Micro-interactions: hover states, active states, icon swaps |
+| 150–200ms | Standard component transitions: dropdowns, tooltips, toasts |
+| 220–300ms | Page-level state changes, drawer open/close, modal appear |
+| 300–500ms | Full-page route transitions |
+| > 500ms | Reserved for intentionally cinematic moments only |
+
+**Rule:** Match duration to the visual weight of the element. A small icon swap at 300ms feels lethargic; a full-page transition at 80ms feels jarring.
+
+---
+
+### 10. Exaggeration
+
+**Animation:** Push key poses slightly beyond reality for emphasis and clarity.
+
+**UX mapping:** Slight overshoot in spring animations communicates energy and intention.
+```tsx
+// Slight overshoot via underdamped spring — not bouncy, but alive
+<motion.div
+  animate={{ scale: 1 }}
+  transition={{ type: "spring", stiffness: 400, damping: 22, mass: 0.8 }}
+/>
+// Peak scale ≈ 1.03–1.05 before settling — imperceptible consciously, felt physically
+```
+**Rule:** Exaggeration in UI should be invisible when you're looking for it. If users notice the bounce, it's too much. Target spring `bounce` values of 0.1–0.2.
+
+---
+
+### 11. Solid Drawing
+
+**Animation:** Characters have weight, depth, and obey perspective; they feel three-dimensional.
+
+**UX mapping:** UI elements should feel visually grounded — not floating. Shadows, depth layering, and transform-origin choices communicate which layer an element lives on.
+- Drawers and sheets slide from an edge — they feel physically attached
+- Modals emerge from center or from the triggering element — they float above the page
+- Tooltips appear near the cursor — they are attached to the pointer
+- `transform-origin` must match where the element conceptually emerges from
+
+---
+
+### 12. Appeal
+
+**Animation:** Characters have a quality that makes the audience want to watch them — not necessarily cute, but interesting.
+
+**UX mapping:** Animation has personality that is consistent with the product's brand.
+
+| Product type | Animation personality |
+|---|---|
+| Financial / serious tools | Crisp, minimal, sub-150ms, no bounce |
+| Consumer apps | Warm, slightly slower, gentle ease-out |
+| Playful / creative tools | Spring physics, slight overshoot, expressive icon animations |
+| Data dashboards | Smooth, purposeful, transitions that reveal data sequentially |
+
+**Rule:** Animation personality must be decided once per product and applied consistently. Mixed personalities (snappy in one area, bouncy in another) destroy cohesion.
+
+---
 
 See also: `reference/motion-easings.md`, `reference/motion-spring.md`, `reference/framer-motion-patterns.md`

package/reference/registry.json

@@ -3,6 +3,27 @@
   "version": 1,
   "generated_at": "2026-04-24T00:00:00.000Z",
   "entries": [
+    {
+      "name": "component-authoring",
+      "path": "reference/component-authoring.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "Kowalski/Sonner 6-principle component quality standard (P-01 Minimal API, P-02 Composability, P-03 Defaults, P-04 Animation as State, P-05 Accessibility First, P-06 Edge Honesty) with grep-able audit signals"
+    },
+    {
+      "name": "emotional-design",
+      "path": "reference/emotional-design.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "Don Norman's visceral/behavioral/reflective three-level cross-cutting scoring lens with per-level rubrics and cross-level conflict patterns"
+    },
+    {
+      "name": "first-principles",
+      "path": "reference/first-principles.md",
+      "type": "heuristic",
+      "phase": 19.6,
+      "description": "3-invariant framework (body/attention/memory) with grep-able principle→code pairs and reducibility test; wired into design-discussant brief stage"
+    },
     {
       "name": "DEPRECATIONS",
       "path": "reference/DEPRECATIONS.md",
@@ -380,6 +401,13 @@
       "type": "heuristic",
       "description": "Nav pattern catalog, menu-depth rules, card sort/tree test benchmarks, wayfinding, faceted nav"
     },
+    {
+      "name": "insight-line.schema",
+      "path": "reference/schemas/insight-line.schema.json",
+      "type": "schema",
+      "tier": "haiku",
+      "description": "JSONL schema for agent run-end insight lines written to .design/intel/insights.jsonl"
+    },
     {
       "name": "intel-schema",
       "path": "reference/intel-schema.md",

package/reference/schemas/insight-line.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AgentInsightLine",
+  "description": "One JSONL line appended by an agent to .design/intel/insights.jsonl at run-end.",
+  "type": "object",
+  "required": ["ts", "agent", "cycle", "stage", "one_line_insight", "artifacts_written"],
+  "additionalProperties": false,
+  "properties": {
+    "ts": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the agent run completion."
+    },
+    "agent": {
+      "type": "string",
+      "description": "Agent name matching the frontmatter 'name' field (e.g. 'design-planner')."
+    },
+    "cycle": {
+      "type": "string",
+      "description": "Active cycle ID from STATE.md (e.g. 'cycle-1'). Empty string if not in a cycle."
+    },
+    "stage": {
+      "type": "string",
+      "description": "Pipeline stage from STATE.md (e.g. 'plan', 'design', 'verify')."
+    },
+    "one_line_insight": {
+      "type": "string",
+      "maxLength": 200,
+      "description": "One declarative sentence: what this agent produced or learned this run."
+    },
+    "artifacts_written": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Relative paths of files written during this run. Empty array for read-only agents."
+    }
+  }
+}

package/reference/shared-preamble.md

@@ -26,6 +26,16 @@ Do not reorder. Do not inline this preamble. Do not splice dynamic content ahead
 
 The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical prefix in the Anthropic cache before a design sprint, so the first real agent spawn of the sprint is already a cache hit on the shared-preamble bytes. You do not need to do anything special to participate — just keep the import directive at the top of your body.
 
+## Design Philosophy Layer (Phase 19.6)
+
+The framework is anchored to three design philosophy references that agents may read during brief, audit, and verify stages:
+
+- `reference/first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
+- `reference/emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
+- `reference/component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
+
+These references encode *why* the heuristics and anti-patterns exist — not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
+
 ---
 
 *Imported by: every file under `agents/*.md` (except `agents/README.md`). Maintained as part of Phase 10.1 (OPT-07) and Phase 14.5 (L0/L2 split). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*