@hegemonart/get-design-done 1.19.0 → 1.19.6

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.19.0"
+    "version": "1.19.6"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, IA catalog, form UX patterns, data-visualization matrix, and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
-      "version": "1.19.0",
+      "version": "1.19.6",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.19.0",
+  "version": "1.19.6",
   "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, information architecture catalog, form UX patterns (Wroblewski label research), data-visualization matrix (25 chart types, Okabe-Ito palette), and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.19.6] — 2026-04-24
+
+### Added — Design Philosophy Layer
+
+Adds a generative reasoning spine on top of the defensive (anti-patterns) and descriptive (heuristics) layers. Purely additive knowledge + lens integration — no new agents, skills, or commands.
+
+**New `reference/first-principles.md`:** 3-invariant framework (body / attention / memory) with grep-able principle→code pairs and a reducibility test for every design element. Wired into `design-discussant` as Step 0.5 — three invariant questions prepended to the brief-stage interview; answers recorded as `[Invariant]` D-XX decisions in STATE.md.
+
+**New `reference/emotional-design.md`:** Don Norman's visceral / behavioral / reflective three-level framework as a cross-cutting scoring lens. Per-level scoring rubrics (1–4) and a cross-level conflict table. Wired into `design-auditor` (Step 4.5 Emotional Design Overlay appended to DESIGN-AUDIT.md) and `design-reflector` (visceral/behavioral divergence check in Section 1).
+
+**New `reference/component-authoring.md`:** Emil 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 and an ARIA contract table by component type. Wired into design-auditor (Pillar 7 sub-check), design-discussant (`--spec` mode question), and design-verifier must-have checklist.
+
+**`reference/heuristics.md` extended:** Added Peak-End Rule, Loss Aversion, Cognitive Load Theory (intrinsic / extraneous / germane), Aesthetic-Usability Effect, Doherty Threshold (400ms), and Flow (Csikszentmihalyi) — completing the psychology foundations layer.
+
+**`reference/motion-advanced.md`:** Disney's 12 Principles UX mapping stub replaced with full authoring — all 12 principles translated to interface motion with code examples (Squash and Stretch, Anticipation, Staging, Straight Ahead vs Pose to Pose, Follow Through, Slow In/Slow Out, Arcs, Secondary Action, Timing, Exaggeration, Solid Drawing, Appeal).
+
+**`reference/checklists.md`:** Added Rams Lens (10 questions mapping Dieter Rams's principles) and Sonner / Component-Authoring Lens (6 P-0N questions) as post-audit self-checks.
+
+**`reference/shared-preamble.md`:** Added Design Philosophy Layer block pointing to the three new reference files — ensures all agents are aware of the philosophy spine.
+
+**`reference/authority-feeds.md`:** Added `jnd.org` (Don Norman) and `vitsoe.com` (Dieter Rams / Vitsœ) as named-practitioner feeds. Feed count: 26 → 28.
+
+**`design-auditor`:** Required reading expanded with `reference/emotional-design.md` and `reference/component-authoring.md`. Step 4.5 (Emotional Design Overlay) added to execution steps.
+
+**`design-discussant`:** Step 0.5 (First-Principles Invariants) prepends three invariant questions during brief/discover stage.
+
+**`design-reflector`:** Section 1 extended with four principles-check prompts: reducibility, memory-load, peak-end, and error-redemption.
+
+---
+
+## [1.19.5] — 2026-04-24
+
+### Added — Cross-Cycle Memory: Recall, Checkpoints, Experience Archive
+
+Turns write-only learnings and reflections into a queryable, ranked, self-pruning memory layer.
+
+**Search backend (`scripts/lib/design-search.cjs`):** Priority chain — FTS5 via `better-sqlite3` (optional dep, runtime-probed) → ripgrep → Node fs scan. `/gdd:recall --reindex` rebuilds the index. `scripts/lib/probe-optional.cjs` wraps optional native deps for future reuse.
+
+**Cross-cycle recall (`/gdd:recall <query>`):** `skills/recall/SKILL.md` — searches `.design/archive/`, `.design/learnings/LEARNINGS.md`, `.design/CYCLES.md`, and STATE.md decision blocks; signals `surfaced` for matched L-NN IDs via `relevance-counter.cjs`.
+
+**Numbered checkpoints (pause/resume rewrite):** `skills/pause/SKILL.md` atomic-appends to `.design/checkpoints/NN-<stage>-<ISO-date>.md` instead of clobbering `HANDOFF.md`; `HANDOFF.md` becomes a pointer to the latest checkpoint. `skills/resume/SKILL.md` gains listing mode with `AskUserQuestion` picker when no arg; `/gdd:resume N` restores checkpoint N. `skills/continue/SKILL.md` — alias for `/gdd:resume` (discoverability).
+
+**Per-cycle EXPERIENCE.md:** `skills/complete-cycle/SKILL.md` extended — Haiku-tier writer reads cycle STATE + DESIGN-VERIFICATION + reflections, emits `.design/archive/cycle-N/EXPERIENCE.md` (~100–200 lines, declarative-fact framing: Goal / Decisions made / Learnings graduated / What died / Surprises / Handoff to next cycle). Highest-priority source for decision-injector.
+
+**Timeline retrospective (`/gdd:timeline`):** `skills/timeline/SKILL.md` — narrative view across EXPERIENCE.md files + git log; sections Opened with / Key decisions / Surprises / What we'd do differently.
+
+**Relevance counter (`scripts/lib/relevance-counter.cjs`):** `record(id, signal, designDir)` under atomic-write + `.lock`; signals: `cited`, `surfaced`, `dismissed`. `shouldPromote` at 8+ cites; `shouldPrune` at 0 cites + 4 cycles.
+
+**Decision-injector FTS5 upgrade:** `hooks/gdd-decision-injector.js` backend-swaps to FTS5 transparently when `design-search.cjs` is available — zero surface-level output change, backend label shown in footer.
+
+**Record contract (mandatory for all agents):** `agents/README.md` authoring template gains mandatory `## Record` step — every agent appends one JSONL line to `.design/intel/insights.jsonl`. `reference/schemas/insight-line.schema.json` — schema with 6 required fields (`ts`, `agent`, `cycle`, `stage`, `one_line_insight`, `artifacts_written`). `tests/record-contract.test.cjs` enforces presence of `## Record` section in every `agents/*.md`. All 36 existing agents updated with stub Record sections.
+
+---
+
 ## [1.19.0] — 2026-04-24
 
 ### Added — Platform, Inclusive Design & UX Research References (knowledge-layer complete)

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue]"
 user-invocable: true
 ---
 
@@ -42,8 +42,11 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `audit [--retroactive] [--quick] [--no-reflect]` | `get-design-done:gdd-audit` | Wraps design-verifier + design-auditor + design-reflector; `--retroactive` audits full cycle scope |
 | `reflect [--dry-run] [--cycle <slug>]` | `get-design-done:gdd-reflect` | On-demand reflection — reads cycle data, produces improvement proposals → `.design/reflections/<slug>.md` |
 | `apply-reflections [--filter <type>] [--dry-run]` | `get-design-done:gdd-apply-reflections` | Review + selectively apply reflection proposals (FRONTMATTER/REFERENCE/BUDGET/QUESTION/GLOBAL-SKILL) |
-| `pause [context]` | `get-design-done:gdd-pause` | Write session handoff to `.design/HANDOFF.md` |
-| `resume` | `get-design-done:gdd-resume` | Restore session context from `.design/HANDOFF.md` and route to next step |
+| `pause [context]` | `get-design-done:gdd-pause` | Write numbered checkpoint to `.design/checkpoints/NN-*.md` |
+| `resume [N]` | `get-design-done:gdd-resume` | Restore session from checkpoint N (or list checkpoints if no arg) |
+| `continue [N]` | `get-design-done:gdd-continue` | Alias for `/gdd:resume` |
+| `recall <query>` | `get-design-done:gdd-recall` | Search cross-cycle memory (decisions, learnings, experience archives) |
+| `timeline [N\|N-M\|all]` | `get-design-done:gdd-timeline` | Narrative retrospective across completed cycles |
 | **Lifecycle** | | |
 | `start [--budget <t>] [--skip-interview] [--dismiss-nudge]` | `get-design-done:start` | First-Run Proof Path — scans UI code, returns one concrete first fix. No STATE.md writes. |
 | `new-project [--name <n>]` | `get-design-done:gdd-new-project` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
@@ -207,7 +210,10 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:watch-authorities  → Skill("get-design-done:gdd-watch-authorities")
 /gdd:benchmark          → Skill("get-design-done:gdd-benchmark")
 /gdd:pause              → Skill("get-design-done:gdd-pause")
-/gdd:resume          → Skill("get-design-done:gdd-resume")
+/gdd:resume             → Skill("get-design-done:gdd-resume")
+/gdd:continue           → Skill("get-design-done:gdd-continue")
+/gdd:recall             → Skill("get-design-done:gdd-recall")
+/gdd:timeline           → Skill("get-design-done:gdd-timeline")
 # --- Lifecycle ---
 /gdd:start           → Skill("get-design-done:start")          # leaf command, no STATE.md
 /gdd:new-project     → Skill("get-design-done:gdd-new-project")

package/agents/README.md

@@ -188,6 +188,59 @@ Constraints: do not modify any file other than .design/example-output.md.
 
 ---
 
+## Mandatory Record Step (Phase 19.5)
+
+Every agent **must** end its run by appending one JSONL line to `.design/intel/insights.jsonl`. This feeds `/gdd:reflect`, `/gdd:extract-learnings`, and the decision-injector relevance counter.
+
+### Format
+
+```json
+{"ts":"2026-01-15T14:23:00.000Z","agent":"design-planner","cycle":"cycle-1","stage":"plan","one_line_insight":"Produced 7-task DESIGN-PLAN.md targeting typography and spacing","artifacts_written":[".design/DESIGN-PLAN.md"]}
+```
+
+### Schema
+
+`reference/schemas/insight-line.schema.json` — all six fields are required.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `ts` | ISO 8601 string | Current UTC time |
+| `agent` | string | Must match frontmatter `name` field |
+| `cycle` | string | From `STATE.md cycle:` — empty string if no active cycle |
+| `stage` | string | From `STATE.md stage:` |
+| `one_line_insight` | string ≤200 chars | Declarative fact: what was produced or learned |
+| `artifacts_written` | string[] | Relative paths written; `[]` for read-only agents |
+
+### Implementation pattern
+
+At the very end of your run (after all writes, before emitting the COMPLETE marker):
+
+```bash
+echo '{"ts":"...","agent":"...","cycle":"...","stage":"...","one_line_insight":"...","artifacts_written":[...]}' >> .design/intel/insights.jsonl
+```
+
+Or via Bash + `node -e` when quoting is complex. Always append (>>), never overwrite. Create `.design/intel/` with `mkdir -p` first.
+
+### Authoring template
+
+Every new agent body must include a `## Record` section before the `## <NAME> COMPLETE` footer:
+
+```markdown
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+\`\`\`json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle>","stage":"<stage>","one_line_insight":"<what was produced>","artifacts_written":["<files>"]}
+\`\`\`
+
+Schema: `reference/schemas/insight-line.schema.json`.
+```
+
+`tests/record-contract.test.cjs` enforces this section is present in every `agents/*.md` file.
+
+---
+
 ## Size Budgets
 
 Agents should be kept small — long instruction bodies burn context at every spawn and drift from their single-responsibility role. Per-tier soft limits:

package/agents/a11y-mapper.md

@@ -141,3 +141,13 @@ Total: N findings. (0 = clean)
 No modifications outside `.design/map/`. No live browser. No git. No agent spawning.
 
 ## A11Y MAP COMPLETE
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/component-benchmark-harvester.md

@@ -105,6 +105,17 @@ This pre-analysis seeds the synthesizer's convergence analysis.
 End your response with:
 
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## HARVEST COMPLETE
 Component: <name>
 Sources harvested: <N>

package/agents/component-benchmark-synthesizer.md

@@ -80,6 +80,17 @@ Update `reference/components/README.md`:
 End your response with:
 
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## SYNTHESIS COMPLETE
 Component: <name>
 Spec: reference/components/<name>.md

package/agents/component-taxonomy-mapper.md

@@ -85,4 +85,14 @@ dominant_styling: [CSS Modules | Tailwind | styled-components | mixed]
 
 Do not modify anything outside `.design/map/`. No git. No agent spawning.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## COMPONENT MAP COMPLETE

package/agents/design-advisor.md

@@ -136,4 +136,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## ADVICE COMPLETE

package/agents/design-assumptions-analyzer.md

@@ -168,4 +168,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## ANALYSIS COMPLETE

package/agents/design-auditor.md

@@ -62,6 +62,8 @@ Minimum expected files:
 - `reference/data-visualization.md` — chart-choice matrix, color-blind palettes, axis conventions (use for chart-heavy projects)
 - `reference/rtl-cjk-cultural.md` — RTL mirroring, CJK typography, cultural color meanings (use when i18n or multi-locale is in scope)
 - `reference/information-architecture.md` — nav pattern catalog, menu-depth rules, wayfinding (use when nav structure is in scope)
+- `reference/emotional-design.md` — Norman's visceral/behavioral/reflective cross-cutting lens; apply after pillar scoring as an informational overlay (see Emotional Design Overlay section below)
+- `reference/component-authoring.md` (if present) — Kowalski/Sonner P-01–P-06 principles; apply as sub-check within Pillar 7 (Micro-Polish) for component-heavy UIs
 
 ---
 
@@ -334,6 +336,16 @@ For each of the 7 pillars:
 
 Write `.design/DESIGN-AUDIT.md` using the output format below.
 
+### Step 4.5: Emotional Design Overlay
+
+After pillar scoring, apply the three-level lens from `reference/emotional-design.md`:
+
+1. **Visceral** — map Pillar 3 (Color) + Pillar 2 (Visual Hierarchy) → does the aesthetic surface convey the intended emotional register within 3 seconds?
+2. **Behavioral** — map Pillar 6 (Experience Design) + H-01/H-09 signals → does feedback arrive within 400ms? Are errors human-readable?
+3. **Reflective** — is there a designed peak moment in the primary flow? Does brand voice carry through to empty states?
+
+Emit a `## Emotional Design Overlay` section in DESIGN-AUDIT.md (informational; does not affect /28 score). Flag any cross-level conflict (e.g., high behavioral + low visceral) as a priority finding.
+
 ### Step 5: Emit Completion Marker
 
 After writing the file, emit `## AUDIT COMPLETE` as the final line of the response.
@@ -528,4 +540,14 @@ If `reference/components/` does not exist or contains no specs, skip this sectio
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## AUDIT COMPLETE

package/agents/design-authority-watcher.md

@@ -205,4 +205,14 @@ On contract violation (schema mismatch, hash format violation, over-200 entries)
 
 Terminate every response with:
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## WATCH COMPLETE

package/agents/design-component-generator.md

@@ -219,3 +219,13 @@ Written: src/components/<ComponentName>.tsx
 DS: <design_system>
 [Preview: <preview_url>]
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-context-checker-gate.md

@@ -87,4 +87,14 @@ You MAY:
 
 Per 10.1-CONTEXT decision **D-21** (Lazy Checker Spawning): "Cheap Haiku gate agents at `agents/*-gate.md` decide whether to spawn full checker. If false, skip full checker, log as `lazy_skipped: true` in telemetry." This gate is the context-checker-specific instance of that pattern — the full `design-context-checker` runs a 6-dimension rubric against `.design/DESIGN-CONTEXT.md`. If the builder made no changes to that file in this phase (a no-op re-run of discover, for example), the prior verdict still holds and the spawn is wasted cost.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## GATE COMPLETE

package/agents/design-context-checker.md

@@ -257,4 +257,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## CONTEXT CHECK COMPLETE

package/agents/design-discussant.md

@@ -32,6 +32,20 @@ The spawning prompt supplies `<required_reading>`. Read every listed file before
 
 If `<connections>` in STATE.md shows `figma: available`, read the `prefix=` field on that line (call it `{P}`). Then `ToolSearch({ query: "figma get_variable_defs", max_results: 5 })` and call `{P}get_variable_defs`. For each returned variable, draft a *tentative* D-XX decision (mark "tentative — confirm with user"). Silently skip on any error. Do NOT grep the codebase.
 
+## Step 0.5 — First-Principles Invariants (brief stage only)
+
+If `<stage>` in the spawning prompt is `brief` or `discover`, prepend these three invariant questions **before** the main design interview. Record answers as D-XX decisions prefixed `[Invariant]` in STATE.md.
+
+Read `reference/first-principles.md` before asking. Questions to ask (one at a time, using `AskUserQuestion`):
+
+1. **Body invariant** — "Are there accessibility requirements for motor-impaired users, or will this be used primarily on mobile devices? (This affects minimum touch target sizes and input method assumptions.)"
+2. **Attention invariant** — "What is the single most important action a user should take on the primary screen? (This will be the only element styled as a primary action.)"
+3. **Memory invariant** — "Are there any multi-step flows where users must carry information from one screen to the next? (This determines whether we need progress indicators or inline context cues.)"
+
+After recording all three answers, apply the **Reducibility Test** framing: note in STATE.md which design elements are invariant-justified (body/attention/memory) and which are decorative.
+
+Skip this step if: `<stage>` is not `brief`/`discover`, if `<mode>` is `--from-handoff` (handoff decisions already encode invariants), or if D-XX decisions prefixed `[Invariant]` already exist in STATE.md.
+
 ## Step 1 — Mode dispatch
 
 Inspect the orchestrator prompt for `<mode>`:
@@ -95,4 +109,14 @@ Write quality log after every exchange. This data feeds `design-reflector`'s que
 - Never grep or glob the codebase — you are a discussant, not a detector.
 - Never spawn other agents.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## DISCUSS COMPLETE

package/agents/design-doc-writer.md

@@ -6,6 +6,8 @@ color: yellow
 model: sonnet
 default-tier: sonnet
 tier-rationale: "Produces polished prose documentation; Sonnet's style quality is sufficient"
+size_budget: XL
+size_budget_rationale: "Phase 19.5 Record contract added ~11 lines; base doc-writer body is 250-line tier"
 parallel-safe: always
 typical-duration-seconds: 45
 reads-only: false
@@ -247,4 +249,14 @@ This agent MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## DOC COMPLETE

package/agents/design-executor.md

@@ -511,4 +511,14 @@ This agent MUST NOT:
 @.design/intel/tokens.json (if present)
 @.design/intel/decisions.json (if present)
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## EXECUTION COMPLETE

package/agents/design-figma-writer.md

@@ -361,3 +361,13 @@ Annotations applied: N/N_total
 Code Connect mappings registered: M/M_total
 Failed: <list any failed operations>
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-fixer.md

@@ -177,4 +177,14 @@ The stage reads the inline summary to determine how many gaps were fixed before
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## FIX COMPLETE

package/agents/design-integration-checker-gate.md

@@ -90,4 +90,14 @@ You MAY:
 
 Per 10.1-CONTEXT decision **D-21** (Lazy Checker Spawning): "Cheap Haiku gate agents at `agents/*-gate.md` decide whether to spawn full checker. If false, skip full checker, log as `lazy_skipped: true` in telemetry." This gate is the integration-checker-specific instance of that pattern — the full `design-integration-checker` is a LARGE-size post-verification spawn that grep-walks the codebase for D-XX decision application. If no decision or anchor doc moved in the diff, the wiring result is unchanged from the last verify and the spawn is wasted cost.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## GATE COMPLETE

package/agents/design-integration-checker.md

@@ -323,4 +323,14 @@ Document any ambiguous cases in the per-decision "Notes" field.
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## INTEGRATION CHECK COMPLETE

package/agents/design-paper-writer.md

@@ -129,3 +129,13 @@ Applied: N/M operations succeeded
 Budget used: N/100 (this session)
 Failed: <list failed operations or "none">
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-pattern-mapper.md

@@ -267,4 +267,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## MAPPING COMPLETE

package/agents/design-pencil-writer.md

@@ -97,3 +97,13 @@ Mode: <mode>
 Applied: N/M operations (N committed, M failed)
 Failed: <list or "none">
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-phase-researcher.md

@@ -226,4 +226,14 @@ flowchart TD
 @.design/intel/dependencies.json (if present)
 @.design/intel/graph.json (if present)
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## RESEARCH COMPLETE

package/agents/design-plan-checker.md

@@ -161,4 +161,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## PLAN CHECK COMPLETE