baldart 3.14.1 → 3.16.0

package/framework/.claude/skills/prd/SKILL.md

@@ -28,6 +28,7 @@ message. You ask questions, wait for answers, and iterate.
 |------|-------|-----------|
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
+| 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
 | 2 | Discovery Question Loop | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | [prd-add-phase.md](references/prd-add-phase.md) |
 | 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
@@ -88,6 +89,17 @@ message. You ask questions, wait for answers, and iterate.
     **Canonical examples**: `FEAT-0875-00..08` (Survey Analytics Redesign),
     `FEAT-0876-00..11` (Menu TIPS). See `assets/epic-template.yml` for the epic
     structure and `assets/card-template.yml` for child structure.
+16. **Mockup Intake (MANDATORY).** Subito dopo Kickoff (Step 1) e prima di entrare in
+    Discovery (Step 2), esegui Step 1.6 — chiedi all'utente se ha mockup a disposizione.
+    Se **sì**: chiedi formato (immagini in chat / path locali), **STOP**, attendi. Sull'arrivo:
+    copia i path locali in `${paths.prd_dir}/<slug>/mockups/`, analizza in dettaglio (vedi
+    [discovery-phase.md](references/discovery-phase.md) § "Mockup analysis schema"), popola
+    `## UI Design` nello state, poi entra in Discovery. Se **no**: marca
+    `mockups.status: none` e procedi col flow standard. Il decision tree di Step 3 (UI Design)
+    consuma `mockups.status` + `screens_in_scope[]` per scegliere ramo Full / Hybrid / Skip
+    senza ulteriore intervento. Le ambiguità rilevate dall'analisi mockup
+    (`mockup_analysis.screens[].gaps[]`) DEVONO diventare domande mirate in Discovery o
+    essere esplicitamente waivate.
 
 ---
 
@@ -122,6 +134,7 @@ At the END of every message (after all text, before stopping), display:
 | # | Fase | Stato |
 |---|------|-------|
 | 1 | Discovery & comprensione | ⬜/🔄/✅ |
+| 1.6 | Mockup intake | ⬜/🔄/✅/⏭️ |
 | 1.5 | Ricerca best practice | ⬜/🔄/✅/⏭️ |
 | 2 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
 | 3 | Conferma specifiche | ⬜/🔄/✅ |
@@ -129,7 +142,9 @@ At the END of every message (after all text, before stopping), display:
 | 5 | Validazione e commit | ⬜/🔄/✅ |
 
 Comprensione: X% (N/M dimensioni coperte) — ISA: N punti identificati
+Mockup: ⬜ non chiesto / 🔄 in attesa / ✅ N mockup / ⏭️ nessuno
 Ricerca: ⬜ non valutata / 🔍 in corso (background) / ✅ completata / ⏭️ non necessaria
+Step 3 mode: full / hybrid / skipped (impostato dopo Step 1.6 e refinementato a Step 3)
 Prossimo passo: <what happens next>
 ```
 
@@ -183,6 +198,16 @@ Dimensions 1-8 can be resolved by: context-primer context (auto), targeted codeb
 Dimension 9 uses automated codebase scan + user validation (see discovery-phase.md).
 Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 
+**Mockup-driven pre-population (when Step 1.6 produced `mockups.status: provided`):**
+- Dimension 5 (UI impact) is largely pre-resolved from `mockup_analysis.screens[]`
+  — log as covered with source `mockup-analysis`. Only ask UI questions for
+  ambiguities in `mockup_analysis.screens[].gaps[]` or for screens NOT in the mockups.
+- Dimension 2 (User journey) is partially pre-resolved from `mockup_analysis.user_flow`
+  — ask only for the connective steps that aren't visible from the mockup sequence
+  (entry point, exit, error branches).
+- All other dimensions follow the normal flow — mockups do not pre-resolve data
+  model, API contract, permissions, edge cases, rollout, ISA, or test strategy.
+
 ---
 
 ## COMPLETED PROGRESS BAR (for final message)
@@ -194,6 +219,7 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 | # | Fase | Stato |
 |---|------|-------|
 | 1 | Discovery & comprensione | ✅ |
+| 1.6 | Mockup intake | ✅/⏭️ |
 | 1.5 | Ricerca best practice | ✅/⏭️ |
 | 2 | Design UI & approvazione | ✅/⏭️ |
 | 3 | Conferma specifiche | ✅ |
@@ -201,7 +227,9 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 | 5 | Validazione e commit | ✅ |
 
 Comprensione: 100%
+Mockup: ✅ N mockup analizzati / ⏭️ nessuno fornito
 Ricerca: ✅ completata / ⏭️ non necessaria
+Step 3 mode: full / hybrid / skipped
 **Pronto per l'implementazione.**
 ```
 
@@ -218,13 +246,13 @@ After cards are created and committed, log this PRD run to `docs/metrics/skill-r
    - `ac_coverage_ratio`: total acceptance_criteria count / total user_stories count across all cards
    - `isa_count`: number of ISA items identified (from the progress bar "ISA: N punti")
    - `has_test_plan_pct`: % of cards that have a `test_plan` field (even if `e2e_required: false`)
-   - `has_firestore_indexes_pct`: % of cards that have a `firestore_indexes` field
+   - `has_db_indexes_pct`: % of cards that have a `db_indexes` field (covers any persistence layer; legacy `firestore_indexes` cards count too)
    - `discovery_iterations`: approximate number of Q&A rounds with the user (count AskUserQuestion calls in this session, default 1 if unknown)
 
 2. Write ONE JSON line (append) to `docs/metrics/skill-runs.jsonl`:
 
    ```json
-   {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_firestore_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
+   {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
 **This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar.

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -6,7 +6,16 @@ id: {{FEAT-ID}}
 title: "{{Full descriptive title}}"
 status: TODO
 priority: {{HIGH|MEDIUM|LOW}}
-owner_agent: claude
+
+# owner_agent — REQUIRED, no implicit default. One of:
+#   coder            → backend / logic / state / data layer / scripts
+#   ui-expert        → UI implementation (mockup → code, registry-first); UI-ONLY scope
+#   plan             → planning-only card (no code edits)
+#   visual-designer  → static visual assets (illustrations, icons, hero images)
+#   motion-expert    → animation specs (timing, easing, micro-interactions)
+# The /new orchestrator dispatches by this field (see new/SKILL.md § Agent Routing).
+# Validation phase BLOCKS commit if value is missing or outside this enum.
+owner_agent: <REQUIRED — coder | ui-expert | plan | visual-designer | motion-expert>
 execution_mode: local
 
 group:
@@ -29,9 +38,18 @@ business_rationale: |
   Aiuta gli agenti implementatori a comprendere l'intento strategico.}}
 
 scope:
+  # UI-only constraint (when owner_agent: ui-expert):
+  # The scope MUST cover ONLY graphical concerns — components, layout, styling,
+  # token usage, motion, accessibility. It MUST NOT bundle business logic, API
+  # integration, data fetching, state management, form validation, or backend
+  # changes. If the step involves both UI and logic, split into two cards
+  # (ui-expert + coder) and wire them via `depends_on:` / `blocks:`.
   summary: |
     {{What this card delivers in 2-3 lines.}}
-  users: [{{CUSTOMER|MERCHANT|SUPER_ADMIN}}]
+  # Drawn from identity.audience_segments[] in baldart.config.yml.
+  # Use the project's own persona labels (e.g. ["customer","merchant"] or
+  # ["admin","editor","viewer"] or ["tenant","support","ops"]).
+  users: [{{persona1, persona2}}]
   value: {{Business value in one line.}}
 
 # --- Scope Boundaries (OPTIONAL — include when card is part of a multi-card epic) ---
@@ -122,13 +140,16 @@ test_plan:
       maps_to: "US-{{N}} / AC-{{N}}"
       priority: {{HIGH|MEDIUM}}
   test_credentials:
-    persona: {{CUSTOMER|MERCHANT|SUPER_ADMIN}}
-    auth_method: "{{OTP|password}}"
-    credentials: "{{phone: 3486417303 | username/password}}"
-    store: "{{store name if merchant}}"
-    notes: "{{e.g., OTP inserito manualmente dall'utente}}"
+    # Persona names come from identity.audience_segments[] in baldart.config.yml.
+    # Credential REFERENCES (not real secrets) live in .baldart/overlays/prd.md
+    # § Test Credentials. Never paste secrets in committed YAML.
+    persona: "{{from identity.audience_segments[]}}"
+    auth_method: "{{OTP | password | magic-link | api-token}}"
+    credentials_ref: "{{secret-manager://path | .env.test:VAR_NAME | overlay-reference}}"
+    context: "{{tenant / workspace / store / org — if applicable}}"
+    notes: "{{e.g., OTP entered manually during test}}"
   test_data_prerequisites:
-    - "{{any Firestore data needed before tests}}"
+    - "{{any data that must exist in the persistence layer before tests run}}"
 
 integration_points:
   - id: ISA-{{N}}
@@ -169,15 +190,17 @@ reuse_analysis:
 # --- Data Sources (MANDATORY — compile for EVERY card; use [] only for pure docs/config cards) ---
 # High-level overview of every data source or destination touched by this card.
 # Rules:
-#   type: firestore → collection name in `path`; field-level detail goes in data_fields below.
+#   type: db        → {entity} name in `path` (collection/table/index per stack.database); field-level detail in data_fields below.
 #   type: file      → repo-relative path, operations (READ|WRITE|APPEND|CREATE|DELETE), format.
 #   type: api       → URL or endpoint pattern; READ=GET, WRITE=POST/PUT/PATCH, DELETE=DELETE.
 #   type: env       → env var name; operations always [READ].
 #   []              → explicit empty list for cards that read/write NO data (docs, config stubs).
 #   NEVER omit this field silently — an empty [] signals the writer verified there are no sources.
+# Legacy "firestore" type is still accepted; prefer "db" + db_dialect.
 data_sources:
-  - type: "{{firestore|file|api|env}}"
-    path: "{{collection name | repo-relative file path | API endpoint | env var name}}"
+  - type: "{{db|file|api|env}}"
+    db_dialect: "{{firestore|postgres|supabase|mysql|mongodb|dynamodb|sqlite}}"  # only when type: db
+    path: "{{entity name | repo-relative file path | API endpoint | env var name}}"
     operations: [{{READ|WRITE|APPEND|CREATE|DELETE}}]
     # format: "{{JSONL|YAML|JSON|markdown|binary}}"  # include for file type only
     # note: "{{optional: data shape, why this source}}"
@@ -194,32 +217,41 @@ env_vars:
     feature_card: "{{nome feature / ID card, es. SPU / ADR-2026-04-24}}"
     note: "{{a cosa serve}}"
 
-# --- Data Fields (MANDATORY for cards that read/write Firestore — omit for UI/docs/config only) ---
+# --- Data Fields (MANDATORY for cards that read/write the persistence layer — omit for UI/docs/config only) ---
 # Structured field-name registry for mechanical validation (pre-commit hook + Quality Audit).
-# Field Grounding Rule: EVERY field here MUST be verified via Grep on field-registry.json
-# BEFORE ts_verified is set to true. See prd-card-writer.md Field Grounding Rule.
-# Fields id, createdAt, updatedAt are universal — do NOT include them here.
+# Field Grounding Rule: EVERY field here MUST be verified via Grep on the schema registry
+# (path resolved per .baldart/overlays/prd.md § Schema Registry — common defaults:
+#  ${paths.references_dir}/field-registry.json for Firestore-style projects,
+#  ${paths.references_dir}/schema.md for SQL, prisma/schema.prisma for Prisma).
+# Fields id, createdAt, updatedAt (or their snake_case equivalents) are universal — do NOT include here.
 data_fields:
-  - collection: "{{collectionName}}"          # exact key in ${paths.references_dir}/field-registry.json
-    field: "{{fieldName}}"                    # exact field name (verified via Grep)
-    type: "{{TypeScript type}}"               # e.g. "string", "OccasionType", "boolean"
+  - entity: "{{collection or table name}}"    # exact key in the project schema registry
+    field: "{{fieldName or column_name}}"     # exact identifier (verified via Grep)
+    type: "{{language-native type}}"          # e.g. "string", "OccasionType", "boolean", "varchar(64)", "JSONB"
     status: "{{existing|new|modified|deprecated_removed}}"
     ts_verified: {{true|false}}               # true = Grep confirmed field in registry
-    source: "{{src/types/booking.ts}}"        # TypeScript file where interface is defined
+    source: "{{src/types/booking.ts | prisma/schema.prisma:42 | migrations/2024_..._create.sql}}"
     # schema_ref: "PRD.md#schema-verification"  # ONLY for status: new fields
 
-firestore_indexes:
-  - collection: "{{collection name}}"
+db_indexes:
+  - entity: "{{collection or table name}}"
+    dialect: "{{firestore|postgres|supabase|mysql|mongodb|dynamodb|sqlite}}"
     fields:
-      - field: "{{field1}}"
-        order: "{{ASC|DESC}}"
-      - field: "{{field2}}"
+      - field: "{{field1 or column1}}"
+        order: "{{ASC|DESC}}"                 # firestore/sql; for mongo use {field1: 1|-1}
+      - field: "{{field2 or column2}}"
         order: "{{ASC|DESC}}"
+    kind: "{{composite|covering|partial|GIN|GSI|LSI|unique|fulltext}}"  # pick what matches dialect
     query_location: "{{file path where the query lives}}"
     prd_ref: "IDX-{{N}}"
-    # Omit this section entirely if the card has no compound Firestore queries.
-    # If present, the coder MUST add these indexes to firestore.indexes.json
-    # in the same commit as the query code.
+    # Omit this section entirely if the card has no compound queries / multi-column indexes.
+    # If present, the coder MUST ship the index in the same commit as the query —
+    # firestore.indexes.json (Firestore), migration file (SQL), createIndex call (Mongo),
+    # CDK/Terraform table definition (DynamoDB).
+
+# Legacy field name kept for backwards-compat with pre-3.15.0 cards. The validator
+# accepts either name; the writer should prefer db_indexes for new cards.
+firestore_indexes: []  # DEPRECATED in v3.15.0 — use db_indexes instead
 
 documentation_impact:
   - "{{doc path}} — {{what to update}}"

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -11,7 +11,7 @@
 # The epic is a TRACKER, not implementation work:
 #   - NO files_likely_touched pointing to code (only docs allowed)
 #   - NO validation_commands, existing_patterns, anti_patterns
-#   - NO data_fields, firestore_indexes
+#   - NO data_fields, db_indexes (firestore_indexes legacy too)
 #   - NO test_plan with scenarios (test scenarios live on children)
 #   - data_sources: [] (always empty)
 #
@@ -26,7 +26,14 @@ id: {{FEAT-XXXX-00}}
 title: "Epic: {{Feature Name}} — {{short tagline}}"
 status: TODO
 priority: {{HIGH|MEDIUM|LOW}}
-owner_agent: claude
+
+# Epics are tracker-only — no implementation work, no dispatcher routing.
+# The /new orchestrator skips epics (it only operates on child cards) and the
+# PRD validation-phase enum-check skips them too. Keep this as an empty
+# string to signal "no specialist assigned"; do NOT use one of the child
+# enum values (coder | ui-expert | plan | visual-designer | motion-expert)
+# on an epic — that would falsely imply the epic carries implementation work.
+owner_agent: ""
 execution_mode: cloud
 
 # Epic's group.parent is the PRD slug (string), NOT a FEAT-ID.
@@ -65,7 +72,8 @@ scope:
   summary: |
     Coordinamento delle {{N}} sub-card che implementano l'epic:
     {{breve descrizione di ogni sub-card in 1 riga ciascuna}}
-  users: [{{CUSTOMER|MERCHANT|SUPER_ADMIN}}]
+  # Drawn from identity.audience_segments[] in baldart.config.yml.
+  users: [{{persona1, persona2}}]
   value: "{{one-line business value}}"
 
 scope_boundaries:

package/framework/.claude/skills/prd/assets/prd-template.md

@@ -44,6 +44,40 @@ Backlog cards to be created after PRD approval.
 |----------|--------|
 | {{doc path}} | {{what to update}} |
 
+## Design Reference & Mockup Inventory
+
+> Omit this entire section only if UI impact is N/A. Otherwise include with
+> `Mockup status: none` when the user did not provide mockups in Step 1.6.
+
+**Mockup status:** {{provided | partial | none | n/a}}
+**Step 3 mode:** {{full | hybrid | skipped}}
+**Design entry point:** {{`docs/prd/<slug>/design.html` | `docs/prd/<slug>/mockups/` | both}}
+
+### Screen inventory
+
+| Schermata | User story | Mockup path | Origine | Note |
+|-----------|------------|-------------|---------|------|
+| {{Lista ordini}} | US-1 | `mockups/lista.png` | mockup utente | tokens align: ✅ |
+| {{Onboarding}} | US-4 | `design.html#onboarding` | generato Step 3b | option scelta: B |
+
+### Mapping schermata → componenti registry
+
+> Populate only when `features.has_design_system: true`. Otherwise remove this
+> subsection.
+
+| Schermata | Componenti riusati | Componenti nuovi | Token violations |
+|-----------|---------------------|------------------|------------------|
+| {{Lista ordini}} | DataTable, Pagination | — | — |
+| {{Dettaglio ordine}} | Card, StatusBadge | OrderTimeline (nuovo — vedi spec) | shadow `0 2px 8px` → `--shadow-card-elevated` |
+
+### Source files originali
+
+Per i mockup forniti come path locali, riportare il percorso utente pre-copia
+(traceability). Per immagini in chat, scrivere `chat://image-N`.
+
+- `{{~/Desktop/orders-mockup.png}}` → `mockups/orders-mockup.png`
+- `chat://image-1` → analizzata inline, non copiata su disco
+
 ---
 
 ## 1. Problem Statement
@@ -99,22 +133,55 @@ Backlog cards to be created after PRD approval.
 
 ## 5. Data Model
 
-{{TypeScript interfaces, Firestore schema changes, validation rules.}}
+{{Type definitions (TypeScript interfaces / Python dataclasses / SQL schema /
+schema validators), persistence-layer schema changes, validation rules.}}
+
+### Database Indexes & Query Optimization
 
-### Firestore Composite Indexes
+> **Stack-specific variant** — populate the variant matching `stack.database`
+> from `baldart.config.yml`. Remove the variants that do not apply. If
+> `stack.database: ""` (unset), the PRD writer SHOULD ask the user which
+> database is in use before completing this section.
 
-Every query that combines `where()` on one field with `orderBy()` on a different field,
-or multiple `where()` on different fields, REQUIRES a composite index. Missing indexes
-cause runtime `FAILED_PRECONDITION` errors (500s in production).
+**Variant A — Firestore** (`stack.database: firestore`)
+
+Every query that combines `where()` on one field with `orderBy()` on a different
+field, or multiple `where()` on different fields, REQUIRES a composite index.
+Missing indexes cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 | # | Collection | Fields | Order | Query Location | Status |
 |---|-----------|--------|-------|----------------|--------|
 | IDX-1 | `{{collection}}` | `{{field1}}` ASC, `{{field2}}` DESC | {{ASC/DESC}} | `{{file:function}}` | NEW / EXISTS |
 
-**Rules:**
-- Every API endpoint or server action that reads from Firestore with compound queries MUST have its indexes listed here.
-- The `firestore.indexes.json` file MUST be updated in the same commit as the query code.
-- If no compound queries are needed: state "Nessun indice composito richiesto — tutte le query usano un singolo campo."
+Rules: every endpoint that reads with compound queries MUST list its indexes
+here; `firestore.indexes.json` MUST be updated in the same commit; if no
+compound queries: "Nessun indice composito richiesto".
+
+**Variant B — Relational (Postgres / Supabase / MySQL / SQLite)**
+
+| # | Table | Columns | Type | Used by | Migration |
+|---|-------|---------|------|---------|-----------|
+| IDX-1 | `{{table}}` | `{{col1}}, {{col2}}` | B-tree / GIN / partial | `{{query location}}` | `{{migration file}}` |
+
+Rules: indexes ship in the same migration as the query; for Supabase, RLS
+policies live alongside in `### Row-Level Security` below; queries on >100k
+rows without a matching index → CRITICAL finding in api-perf-gate.
+
+**Variant C — MongoDB**
+
+| # | Collection | Fields | Type | Used by | Notes |
+|---|-----------|--------|------|---------|-------|
+| IDX-1 | `{{collection}}` | `{{field1}}: 1, {{field2}}: -1}` | compound / text / 2dsphere | `{{aggregation pipeline}}` | TTL / partial / sparse if applicable |
+
+**Variant D — DynamoDB**
+
+| # | Table | PK / SK | GSI / LSI | Access Pattern | Notes |
+|---|-------|---------|-----------|----------------|-------|
+| GSI-1 | `{{table}}` | `{{pk}} / {{sk}}` | GSI: {{name}} on {{attrs}} | {{query pattern}} | provisioned / on-demand |
+
+**Variant E — None / no DB / N/A**
+
+State explicitly: "Feature is stateless / does not touch the persistence layer".
 
 ---
 
@@ -126,7 +193,12 @@ cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 ## 7. UI Specifications
 
-{{Layout, components, styling, responsive behavior, a11y.}}
+> Canonical visual reference: **Design Reference & Mockup Inventory** section above.
+> This section describes specs that are NOT obvious from the mockups themselves
+> (behavioral, responsive breakpoints, a11y, motion, copy variants by locale).
+> Do NOT duplicate the screen list or component table — link to them above.
+
+{{Layout details not visible in mockups, responsive behavior, a11y, motion, copy variants.}}
 
 ---
 
@@ -191,10 +263,14 @@ cause runtime `FAILED_PRECONDITION` errors (500s in production).
 
 ### Test Credentials
 
-| Persona | Auth Method | Credentials | Notes |
-|---------|------------|-------------|-------|
-| {{Consumer}} | OTP | phone: 3486417303 | OTP inserito manualmente dall'utente durante il test |
-| {{Merchant}} | password | {{username}} / {{password}} | Store: {{store name}} |
+> Personas drawn from `identity.audience_segments[]`. Credential values come
+> from `.baldart/overlays/prd.md § Test Credentials` (preferred), or were asked
+> to the user during discovery. **Do NOT paste real secrets here** — use
+> references to a secret manager / `.env.test` / 1Password item.
+
+| Persona | Auth Method | Credentials Reference | Notes |
+|---------|-------------|-----------------------|-------|
+| {{audience_segments[0]}} | {{OTP / password / magic link / token}} | {{secret-manager://path or .env.test:VAR}} | {{notes about context, tenant, store, etc.}} |
 
 ### Test Data Prerequisites
 

package/framework/.claude/skills/prd/assets/state-template.md

@@ -67,6 +67,24 @@ Scenarios: pending
 
 ## UI Design
 
+mockups.status: pending           # none | requested | provided | partial
+mockups.format: pending           # chat-images | local-paths | mixed
+mockups.original_paths: []        # user-provided paths or chat://image-N
+mockups.canonical_paths: []       # mockups/<file> after copy
+
+mockup_analysis.screens: []       # see discovery-phase.md § Mockup analysis schema
+mockup_analysis.user_flow: []
+mockup_analysis.design_system_alignment:
+  status: pending                 # aligned | violations | not-applicable
+  violations: []
+
+step_3_mode: pending              # full | hybrid | skipped
+design.html_path: pending         # path | n/a (mockup-only)
+
+screens_in_scope: []              # [{ name, covered_by_mockups: bool, generated_in_step_3b: bool }]
+
+ui_inventory: []                  # populated by Step 3d
+
 ## Confirmed Specs
 
 ## Backlog Cards