baldart 3.14.1 → 3.16.0

package/framework/.claude/skills/prd/references/discovery-phase.md

@@ -72,8 +72,118 @@ la feature prima di scrivere qualsiasi documento.
 
 **Gate:** state file exists on disk AND all tasks created AND context loaded.
 
-**Immediately proceed to Step 2** — do NOT stop here. Show the kickoff message
-and continue to the discovery loop in the same turn.
+**Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
+and ask the mockup intake question in the same turn.
+
+## Step 1.6 — Mockup Intake (MANDATORY)
+
+Runs between Kickoff (Step 1) and Discovery (Step 2). Cannot be skipped.
+
+**Purpose:** detect whether the user already has mockups for this feature, archive
+them as canonical artefacts, and feed the visual analysis into Discovery alongside
+the codebase context from `/cont`. The Step 3 (UI Design) decision tree consumes the
+result.
+
+### 1.6.1 — Ask
+
+After the kickoff output (Step 1, point 7), append this question to the SAME message:
+
+```
+### Domanda — Mockup
+
+Hai dei mockup a disposizione per questa feature?
+
+- **Sì** → posso analizzarli prima di iniziare la discovery, così le domande
+  saranno calibrate su quello che è già definito visivamente.
+- **No** → procediamo con la discovery standard; se serve, in Step 3 genero
+  io 3 opzioni di design.
+```
+
+**STOP.** Display Progress Bar (row `1.6 Mockup intake: 🔄`) and wait for the user.
+
+### 1.6.2 — Answer = "No"
+
+- Update state file `## UI Design`: `mockups.status: none`.
+- Mark progress bar row `1.6 ✅ (no mockups)`.
+- **Immediately proceed to Step 2** in the same turn. No further STOP.
+
+### 1.6.3 — Answer = "Sì"
+
+Append this follow-up to the SAME message:
+
+```
+Perfetto. In che forma me li passi?
+
+- **Immagini in chat** — incollale direttamente nel prossimo messaggio.
+- **Path locali** — incolla i percorsi (assoluti o relativi al repo) e li copio
+  in `${paths.prd_dir}/<slug>/mockups/`.
+- **Misti** — entrambe le cose.
+```
+
+- Update state file `## UI Design`: `mockups.status: requested`, `mockups.format: pending`.
+- **STOP.** Wait for the user.
+
+### 1.6.4 — Mockup reception & archival
+
+When the user replies with the mockups:
+
+1. **Detect format** and update `mockups.format` ∈ {`chat-images`, `local-paths`, `mixed`}.
+2. **For each local path provided:**
+   - Resolve to absolute path. If file does not exist: ask the user to confirm/correct
+     (do not silently skip).
+   - Ensure `${paths.prd_dir}/<slug>/mockups/` exists (create if missing).
+   - Copy the file into that directory, preserving filename. On collision (file with
+     same name already there): append numeric suffix (`<name>-2.png`).
+   - Record both paths in state: `mockups.original_paths[]` and `mockups.canonical_paths[]`.
+3. **For chat images:** record in state `mockups.original_paths[]` as `chat://image-N`
+   (the images remain in the conversation context window).
+4. Update `mockups.status: provided` (or `partial` only if the user explicitly says
+   "ho solo questi 2 ma servono anche altri").
+
+### 1.6.5 — Mockup analysis (MANDATORY before Discovery)
+
+Analyze ALL provided mockups (visual analysis for chat images, Read for copied files
+that are textual like HTML/SVG). Populate `## UI Design` in the state file using the
+**Mockup analysis schema** (see appendix at the end of this file).
+
+When `features.has_design_system: true`, BLOCKING reads of `${paths.design_system}/INDEX.md`
+and `${paths.design_system}/tokens-reference.md` apply BEFORE running the alignment
+check — same protocol as Step 3 (UI Design). Flag every hardcoded value (hex / shadow /
+radius / spacing) that conflicts with a known token as a violation in
+`mockup_analysis.design_system_alignment.violations[]`.
+
+### 1.6.6 — Output and handoff to Discovery
+
+After analysis is complete, present to the user:
+
+```
+Mockup acquisiti e analizzati: N schermate identificate.
+
+Schermate: <list>
+Flusso utente inferito: <one-line summary>
+Componenti riconosciuti: N (X riusati dal registry, Y nuovi)
+Stati visibili: <empty/loading/error/success per schermata se rilevanti>
+Allineamento design system: <aligned | N violations to resolve in Step 3>
+Gap da chiarire in discovery: <list of ambiguities, max 5>
+
+Ora entro in **Discovery** — le domande saranno calibrate su quanto già definito
+nei mockup. Le ambiguità rilevate diventeranno domande mirate.
+
+<Progress Bar>
+```
+
+- Mark progress bar row `1.6 ✅` (or `🔄` if `partial`).
+- **Immediately proceed to Step 2** in the same turn.
+
+### Coordination with `/cont`
+
+The `/cont` skill invoked in Step 1.5 runs synchronously and completes before the
+kickoff output. The mockup intake question is asked in the same message; if the user
+answers "Sì", the STOP gives the codebase context time to settle in conversation
+history while we wait. When the mockups arrive, the visual analysis combines with the
+already-loaded codebase context to inform Discovery dimension selection (especially
+dimension 5 UI impact and partially dimension 2 User journey, both of which can be
+pre-populated from `mockup_analysis`).
 
 ## Step 2 — Discovery Question Loop
 
@@ -171,6 +281,16 @@ section of the state file. Mark dimension as covered.
        the Change Request flow. After it completes, resume discovery from the
        next uncovered dimension.
      - If user says out-of-scope: note in Discovery Log and continue.
+   - **New-Screen Check** (only when `mockups.status` ∈ {`provided`, `partial`}):
+     When the user's answer reveals a UI screen NOT present in
+     `mockup_analysis.screens[]`, do NOT treat it as a scope expansion. Instead,
+     append the screen to `screens_in_scope[]` in the state file with
+     `covered_by_mockups: false`. Log inline:
+     `Ho rilevato una nuova schermata non presente nei mockup: **<name>**. La
+     genero in Step 3 (modalità ibrida) solo per quella schermata.`
+     Continue with the next dimension. This is a routine signal for Step 3, not
+     a scope expansion — the Scope Expansion Check above still applies for
+     non-UI entities (endpoints, roles, collections).
    - Update state file
    - Proceed to next uncovered dimension (back to action 1)
 
@@ -274,30 +394,41 @@ Instead, run the E2E Evaluation Decision Tree and present the result.
 **When E2E is REQUIRED or user accepts RECOMMENDED:**
 
 1. Identify test scenarios from user stories and acceptance criteria (2-5 scenarios max).
-2. Determine test persona:
-
-   **Consumer feature** (target users include CUSTOMER):
-   - Auto-set credentials: `phone: 3486417303, auth: OTP (manual input by user during test)`
-   - Inform user: `Credenziali test consumer: 3486417303 (OTP manuale durante il test).`
-   - No question needed.
-
-   **Merchant feature** (target users include MERCHANT or MERCHANT_STAFF):
-   - ASK the user:
-     ```
-     ### Domanda — Credenziali test merchant
-
-     Questa feature richiede test E2E come merchant.
-     Su quale merchant e store vuoi testare?
-     Servono le credenziali di login (username/password).
-
-     Esempio: antonio.baldassarre2336 / bRkS2bzqyesK su store "Bar Roma"
-     ```
-   - **STOP.** Wait for user response. Store credentials in state file under `## Test Plan`.
-
-   **Super Admin feature** (target users include SUPER_ADMIN):
-   - ASK the user for admin credentials (same pattern as merchant).
-
-   **Mixed personas**: gather credentials for each persona that needs E2E.
+2. **Determine test personas** by intersecting:
+   - The user-stories' `As a <persona>` field, and
+   - `identity.audience_segments[]` from `baldart.config.yml` (single source of truth
+     for the project's personas — NEVER hardcode persona names in the skill).
+
+   For each persona that needs E2E coverage, gather credentials using the following
+   resolution order:
+
+   **a. Consult `.baldart/overlays/prd.md`** (if present) for a `## Test Credentials`
+      section. If the overlay defines a default credential pattern for the persona
+      (e.g. `customer → phone OTP`, `merchant → username/password`), use it and
+      log inline: `Credenziali test {{persona}}: caricate da overlay.`
+      Do NOT print the actual credential values inline — only confirm the source.
+
+   **b. Otherwise ASK the user**, ONE question per persona:
+      ```
+      ### Domanda — Credenziali test {{persona}}
+
+      Questa feature richiede test E2E con la persona **{{persona}}**.
+      Fornisci le credenziali di test (o un riferimento all'ambiente di test):
+
+      - Metodo di auth: <es. password / OTP via SMS / magic link / API token>
+      - Identificativo: <es. username, email, phone>
+      - Secret: <password, OTP source, token — meglio NON incollarlo in chat,
+        usa un riferimento al vault>
+      - Contesto (se rilevante): <es. tenant, workspace, store, organization>
+      ```
+      **STOP.** Wait for user response. Store the *minimum-necessary* credential
+      reference in the state file under `## Test Plan` — prefer a reference to a
+      secret manager / 1Password / `.env.test` path over the literal secret.
+
+      Suggerisci all'utente di consolidare la risposta in `.baldart/overlays/prd.md`
+      (sezione `## Test Credentials`) per evitare la stessa domanda ai PRD futuri.
+
+   **c. Mixed personas:** ripeti b. per ciascuna persona non risolta da a.
 
 3. After credentials are gathered, summarize the test plan:
    ```
@@ -305,8 +436,8 @@ Instead, run the E2E Evaluation Decision Tree and present the result.
 
    E2E: REQUIRED | RECOMMENDED (accettato)
    Scenari: N test scenarios
-   Persona: [Consumer | Merchant | Super Admin | Mixed]
-   Credenziali: [summary]
+   Personas coinvolte: <list from identity.audience_segments[] involved>
+   Sorgente credenziali: [overlay | user-provided | mixed]
 
    Scenari pianificati:
    1. [scenario description — maps to US-X / AC-X]
@@ -315,6 +446,11 @@ Instead, run the E2E Evaluation Decision Tree and present the result.
 
 4. Mark dimension as covered. Update state file `## Test Plan` section.
 
+> **Security note:** the framework MUST NOT contain any real test credential
+> (phone numbers, usernames, passwords, tokens). All credential examples in this
+> file are intentionally generic. Project-specific defaults live in
+> `.baldart/overlays/prd.md` (consumer-owned, not redistributed).
+
 ### Research Trigger (evaluated at ~75% comprehension)
 
 When 6+ non-test dimensions are covered, evaluate complexity signals from
@@ -357,3 +493,53 @@ Passo alla fase successiva: [UI Design / Scrittura PRD]
 
 <Progress Bar>
 ```
+
+---
+
+## Appendix — Mockup analysis schema
+
+Used by Step 1.6.5. Populate the `## UI Design` section of the state file with this
+structure. Be specific — vague analysis defeats the purpose of skipping Step 3.
+
+```yaml
+mockups:
+  status: provided | partial | none | requested
+  format: chat-images | local-paths | mixed
+  original_paths:
+    - <user-provided path or chat://image-N>
+  canonical_paths:
+    - mockups/<file>.png         # only for local-paths
+mockup_analysis:
+  screens:
+    - name: <inferred name, e.g. "Lista ordini">
+      mockup_ref: <canonical_path or chat://image-N>
+      purpose: <one line — what this screen lets the user do>
+      components:
+        - <component name from ${paths.design_system}/INDEX.md if matched, else free-form>
+      states_visible: [empty, loading, error, success, default]
+      copy_excerpts:
+        - <verbatim text visible in the mockup, max ~10 strings per screen>
+      gaps:
+        - <ambiguity to clarify in Discovery, e.g. "filtro per data: range o singola?">
+  user_flow:
+    - <step 1, e.g. "Utente apre Lista ordini → tap su riga → Dettaglio ordine">
+  design_system_alignment:
+    status: aligned | violations | not-applicable
+    violations:
+      - mockup: <screen name>
+        kind: hardcoded-color | hardcoded-spacing | hardcoded-shadow | hardcoded-radius | custom-component
+        detail: <e.g. "background #FF6A00 — token equivalent: --color-brand-primary">
+        fix_in_step_3: <token name or component to swap in>
+```
+
+**When NOT to fill a field:**
+- Omit `design_system_alignment` entirely (do NOT write `not-applicable`) when
+  `features.has_design_system: false` — the field becomes irrelevant.
+- Omit `copy_excerpts` for screens that have no readable text (icon-only).
+- Omit `states_visible` for screens that show only the default state — do not
+  invent states the mockup doesn't show.
+
+**Gap discipline:** every entry in `gaps[]` MUST become either a Discovery question
+or an explicit non-question (recorded in Discovery Log as "skipped — outside
+mockup scope"). Gaps that remain unresolved by the end of Discovery block PRD
+writing in Step 4.

package/framework/.claude/skills/prd/references/prd-writing-phase.md

@@ -17,6 +17,11 @@ Mark task 3 as `in_progress`.
    - Read `docs/guides/linking-protocol-rollout-v1.md` for the Canonical Ownership Matrix.
    - Identify which existing PRDs, ADRs, reference docs, or backlog cards are canonical
      for this feature area.
+   - **Mockup-derived canonical sources** (when `mockups.status` ∈ {`provided`, `partial`}
+     in state file): treat `${paths.prd_dir}/<slug>/mockups/` as a canonical visual
+     reference. Add a row to the PRD Canonical Sources table:
+     `| Mockup originali | ${paths.prd_dir}/<slug>/mockups/ |`. If chat images were
+     analyzed without being copied to disk, add: `| Mockup chat | inline in PRD session — see Design Reference section |`.
 3. **Incorporate research findings** (if `## Research Findings` in state file is populated):
    - Reference best practices in data model, API, and architecture decisions.
    - Cite sources in PRD rationale sections.
@@ -24,42 +29,65 @@ Mark task 3 as `in_progress`.
    - If regulatory findings exist: add a dedicated "Compliance Requirements" section.
    - Include a "Research-Informed Decisions" subsection listing decisions influenced
      by research, with brief rationale and source reference.
-3.5. **Schema Verification Gate (MANDATORY if feature touches Firestore)**
+3.5. **Schema Verification Gate (MANDATORY if feature touches the persistence layer)**
 
-   If any of the following apply: new Firestore collection, modified fields, compound queries,
-   or reading/writing existing documents — run this gate before writing Section 3 (Data Model).
+   Read `stack.database` from `baldart.config.yml`. If empty AND the feature
+   description mentions data persistence, ASK the user which database is in
+   use and persist the answer to `baldart.config.yml` (offer `npx baldart
+   configure` if multiple keys are missing). Skip this gate when
+   `stack.database: none` or the feature is stateless.
+
+   The vocabulary in this gate adapts to `stack.database`:
+   - Firestore / MongoDB / DynamoDB → "collections" / "documents" / "fields"
+   - Postgres / Supabase / MySQL / SQLite → "tables" / "rows" / "columns"
+   The procedure below uses **{entity}** = collection|table and **{field}** =
+   field|column.
+
+   If any of the following apply: new {entity}, modified {field}s, compound
+   queries, or reading/writing existing rows/documents — run this gate before
+   writing Section 5 (Data Model).
 
    **Procedure:**
-   1. Identify every collection the feature uses or modifies.
-   2. For each collection: read `${paths.references_dir}/field-registry.json` → find the collection key.
+   1. Identify every {entity} the feature uses or modifies.
+   2. For each {entity}: read the project schema registry. The path is
+      project-specific — common locations: `${paths.references_dir}/field-registry.json`
+      (Firestore-style projects), `${paths.references_dir}/schema.md` (SQL),
+      `${paths.references_dir}/collections/*.md` (per-collection markdown), or
+      the migrations dir for SQL projects (`migrations/`, `db/migrate/`,
+      `prisma/schema.prisma`, `supabase/migrations/`). Resolution order: check
+      `.baldart/overlays/prd.md § Schema Registry` first if defined; otherwise
+      pick the convention matching `stack.database`.
    3. Build a `## Schema Verification` section in the PRD (see template below).
-   4. Mark each field: `✅ existing` | `🆕 new` | `❌ NOT FOUND`.
-   5. **GATE**: if ANY field is `❌ NOT FOUND` and NOT marked as `🆕 new`:
+   4. Mark each {field}: `✅ existing` | `🆕 new` | `❌ NOT FOUND`.
+   5. **GATE**: if ANY {field} is `❌ NOT FOUND` and NOT marked as `🆕 new`:
       - STOP — do not advance to Section 5 (backlog cards).
-      - Ask the user: "Is `fieldName` in collection `collectionName` a new field or a naming error?"
-      - If new: add full schema definition in PRD Section 3 and mark `🆕`.
+      - Ask the user: "Is `{fieldName}` in {entity} `{entityName}` a new {field} or a naming error?"
+      - If new: add full schema definition in PRD Section 5 and mark `🆕`.
       - If error: correct the name.
 
    **Template `## Schema Verification`** (insert after PRD Acceptance Criteria section):
 
    ```markdown
    ## Schema Verification
-   > Source: field-registry.json — verificato il {YYYY-MM-DD}
-   > Complessità stimata: HIGH | MEDIUM | LOW
+   > Source: {schema-registry-path} — verified on {YYYY-MM-DD}
+   > Database: {stack.database}
+   > Complexity: HIGH | MEDIUM | LOW
 
-   ### Collection: {collectionName}
+   ### {entity}: {entityName}
 
-   | Field | Type | Status | Note |
-   |-------|------|--------|------|
+   | {field} | Type | Status | Note |
+   |---------|------|--------|------|
    | `fieldName` | string | ✅ existing | — |
-   | `newField` | string | 🆕 new | schema in Section 3 |
-   | `~~oldField~~` | — | ❌ NOT FOUND | correggi nome |
+   | `newField` | string | 🆕 new | schema in Section 5 |
+   | `~~oldField~~` | — | ❌ NOT FOUND | rename mismatch |
 
-   ### Blocchi aperti
-   - (nessuno) — oppure lista dei ❌ con azione richiesta
+   ### Open issues
+   - (none) — or list of ❌ with required action
    ```
 
-   **Nota**: `id`, `createdAt`, `updatedAt` sono universali — non richiedono verifica.
+   **Universal fields:** auto-PK/ID, `createdAt`/`created_at`,
+   `updatedAt`/`updated_at` are universal in their stack — do not require
+   verification.
 
 4. Write `docs/prd/<slug>/PRD.md` using the template from `assets/prd-template.md`.
 
@@ -72,13 +100,27 @@ Every PRD MUST include these sections (remove only when genuinely N/A):
 - Goals / non-goals
 - Personas
 - User stories
-- Data model (TypeScript interfaces, Firestore schema changes, validation rules, **Firestore Composite Indexes table** — MANDATORY if any compound query exists)
+- Data model (type definitions matching the language stack, persistence-layer
+    schema changes, validation rules, **Database Indexes & Query Optimization
+    table** — MANDATORY if any compound query / multi-column index exists. Pick
+    the variant matching `stack.database`: Firestore Composite, Postgres B-tree,
+    MongoDB compound, DynamoDB GSI/LSI. See `assets/prd-template.md § 5`.)
 - API contract changes (endpoints, request/response, validation)
+- **Design Reference & Mockup Inventory** (if UI impact ≠ N/A — populate from
+    `mockups.*`, `mockup_analysis.*`, `step_3_mode`, and `screens_in_scope[]` in
+    the state file. Include the screen inventory table, the component mapping
+    table when `features.has_design_system: true`, and the source-files
+    traceability list. When `mockups.status: none`, the section is still present
+    with the table empty and a note "Design generato in Step 3 — vedi design.html".)
 - UI specifications (if applicable — MUST derive from `## UI Element Inventory` in
-    state file; include the full inventory table verbatim, reference `design.html` path,
-    and map each UI element to the requirement it satisfies)
+    state file; include the full inventory table verbatim, reference `design.html` path
+    OR `mockups/` directory when `step_3_mode: skipped`, and map each UI element to
+    the requirement it satisfies. Do NOT duplicate the screen list from the Design
+    Reference section above — link to it.)
 - i18n specification (dictionary keys, locale files)
-- Acceptance criteria (grouped by area: Merchant, Customer, API, i18n)
+- Acceptance criteria (grouped by area: one group per persona drawn from
+    `identity.audience_segments[]`, plus cross-cutting groups: API, i18n,
+    Observability if relevant)
 - Edge cases and failure modes (table format)
 - Out of scope
 - Dependencies (table with type and status)

package/framework/.claude/skills/prd/references/research-phase.md

@@ -42,9 +42,21 @@ Scan discovery answers and codebase-architect findings for these signals:
 Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
 
 1. **Identify research topics** from the matching signals. Formulate 1-3
-   specific research questions. Examples:
-   - S1: "Best practices for implementing [pattern] in a Next.js/Firestore stack"
-   - S2: "Regulatory requirements for [topic] in Italy/EU, implementation checklist"
+   specific research questions. Build the stack signature dynamically from
+   `baldart.config.yml`:
+
+   ```
+   stack_signature = "{{stack.framework}} + {{stack.database}} + {{stack.auth_provider}}"
+   # Examples it might resolve to:
+   #   "nextjs + firestore + firebase-auth"
+   #   "remix + supabase + supabase-auth"
+   #   "sveltekit + postgres + lucia"
+   # If any segment is empty, omit it from the signature.
+   ```
+
+   Examples of research questions (substitute {stack_signature} at runtime):
+   - S1: "Best practices for implementing [pattern] on a {stack_signature} stack"
+   - S2: "Regulatory requirements for [topic] in {{identity.language country}}, implementation checklist"
    - S3: "Integration patterns for [service], comparison of approaches, gotchas"
    - S4: "UX best practices for [pattern], accessibility considerations, mobile"
    - S6: "Trade-offs of [approach A] vs [approach B] for [use case]"
@@ -58,13 +70,19 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
      prompt: "Research the following topics for a PRD we're writing for feature
        '<slug>'. Context: <1-2 line feature summary>.
 
+       Project stack (from baldart.config.yml):
+       - framework: {{stack.framework or 'unspecified'}}
+       - database: {{stack.database or 'unspecified'}}
+       - auth_provider: {{stack.auth_provider or 'unspecified'}}
+       - deployment: {{stack.deployment or 'unspecified'}}
+
        Research questions:
        1. <question>
        2. <question>
 
        For each topic, provide:
        - Summary of best practices (with sources)
-       - Recommended approach for our stack (Next.js 16, Firestore, Firebase Auth)
+       - Recommended approach for the project stack above
        - Key gotchas or anti-patterns to avoid
        - If applicable: regulatory checklist or compliance requirements
 

package/framework/.claude/skills/prd/references/ui-design-phase.md

@@ -1,8 +1,18 @@
 # UI Design Phase (Step 3)
 
-Skip entirely if UI impact dimension is N/A. Proceed to PRD Writing Phase.
+## Precondition decision tree
 
-Mark task 2 as `in_progress`.
+Read `mockups.status` and `screens_in_scope[]` from the state file `## UI Design`
+section (populated by Step 1.6) plus the UI impact dimension from the discovery
+checklist. Pick exactly one branch:
+
+| Condition | Branch | Action |
+|-----------|--------|--------|
+| UI impact = N/A | **Skip totale** | Mark task 2 `completed` ("Skipped — no UI"). `step_3_mode: skipped`. Proceed to PRD Writing Phase. |
+| `mockups.status: none` AND UI impact ≠ N/A | **Full** | Run the standard pipeline 3a → 3b → 3c → 3d as before. `step_3_mode: full`. |
+| `mockups.status` ∈ {`provided`, `partial`} AND UI impact ≠ N/A | **Hybrid** | Per-screen routing (see § Hybrid mode below). `step_3_mode: hybrid` (or `skipped` if every screen is covered AND no `mockup_analysis.design_system_alignment.violations`). |
+
+Mark task 2 as `in_progress` for the Full and Hybrid branches.
 
 ## Delegation to `ui-design` Skill
 
@@ -50,7 +60,7 @@ MISSING — no match found:
 
 This prevents designing new components when 450+ reusable ones already exist.
 
-### Gates (same as before)
+### Gates (Full branch)
 
 - **After Step 3b:** all 3 polished options open in Safari AND screenshots shown inline.
   **STOP.** Wait for user to choose.
@@ -59,3 +69,105 @@ This prevents designing new components when 450+ reusable ones already exist.
   is populated in the state file with at least 3 elements.
 
 Mark task 2 as `completed`. Update state file status to `specs-confirmed`.
+
+---
+
+## Hybrid mode (Step 1.6 produced mockups)
+
+Triggered when `mockups.status` ∈ {`provided`, `partial`}. The principle: the user
+has already done the design work for some screens — don't redo it. Validate, align
+to the design system, approve, and inventory. Generate ONLY the screens not covered.
+
+### Build the per-screen routing table
+
+1. Construct `screens_in_scope[]` by merging:
+   - User Stories from the state file (one row per US that implies a screen).
+   - ISA `NAVIGATION` and `DASHBOARD` touchpoints that imply landing screens.
+   - The `mockup_analysis.screens[]` list itself (in case the mockups include
+     screens the user stories didn't make explicit).
+2. For each entry, set `covered_by_mockups: true` iff the screen matches a
+   `mockup_analysis.screens[].name` (case-insensitive substring match is fine —
+   when ambiguous, ASK the user "questa schermata `<X>` corrisponde al mockup
+   `<Y>`?" and STOP).
+3. Persist `screens_in_scope[]` in the state file `## UI Design` section.
+
+### Per-screen execution
+
+| `covered_by_mockups` | What runs | Notes |
+|----------------------|-----------|-------|
+| `true` | Component Registry Lookup (adapted) + 3c (approval gate) + 3d (save & inventory) | SKIP 3a (options) and 3b (generation). Use the provided mockup as the canonical reference. |
+| `false` | Subskill `ui-design` 3a + 3b SCOPED TO THIS SCREEN, then 3c + 3d | Pass the screen name + relevant discovery answers + context-primer output. Mockups for OTHER screens already approved are passed as "existing design language to match" so the new screen looks consistent. |
+
+### Step 3 sub-flow in Hybrid mode
+
+1. **Component Registry Lookup (all screens, before any generation).**
+   For each screen — covered OR new — match `mockup_analysis.screens[].components[]`
+   (covered) or the inferred component list (new) against
+   `${paths.references_dir}/component-registry.md` and, when
+   `features.has_design_system: true`, against `${paths.design_system}/INDEX.md`.
+   - For covered screens: any component used in a mockup but NOT in the registry
+     becomes either (a) a REUSE recommendation if a close match exists, or (b) a
+     candidate new primitive — flag in `mockup_analysis.design_system_alignment`.
+   - For new screens: passed to `ui-design` as the REUSE list (prevents the
+     subskill from inventing new components).
+2. **Generation pass (new screens only).**
+   For each new screen, invoke `Skill(ui-design)` with payload:
+   ```
+   feature_slug: <slug>
+   scope: single-screen
+   screen_name: <X>
+   discovery_excerpt: <answers relevant to this screen>
+   reuse_components: <list from registry lookup>
+   design_language_anchor: mockups/<existing-mockup-1>.png, mockups/<existing-mockup-2>.png
+   ```
+   The subskill produces 3 options for that one screen (its standard 3b output).
+   Open in Safari, **STOP**, wait for user to choose.
+3. **Approval gate (all screens, 3c).**
+   Present in ONE message:
+   - Thumbnail + path for each `covered_by_mockups: true` screen.
+   - The user-chosen option for each `generated_in_step_3b: true` screen.
+   - All `design_system_alignment.violations[]` consolidated into a "Issues da
+     risolvere prima di Step 4" list with the proposed token/component swap.
+   Ask explicit confirmation ("confermo", "va bene", "ok"). **STOP.**
+4. **Save & Inventory (all screens, 3d).**
+   - For covered screens: copy `mockups/<file>.png` references into the unified
+     UI Element Inventory; no `design.html` regeneration needed unless the subskill
+     also ran. If at least one new screen was generated, the merged `design.html`
+     includes both the new mockups and embeds/links to the existing ones.
+   - For all-covered runs (`generated_in_step_3b: false` everywhere): set
+     `design.html_path: n/a (mockup-only)` in the state file; the PRD will link
+     directly to `${paths.prd_dir}/<slug>/mockups/`.
+   - Update `## UI Element Inventory` in the state file with at least one row per
+     covered screen + per generated screen.
+
+### Hybrid gates
+
+- **After per-screen 3b (only if any new screen exists):** all 3 polished options
+  per new screen open in Safari AND screenshots shown inline. **STOP.** Wait for
+  user choice.
+- **After 3c (approval):** explicit user approval AND every entry in
+  `design_system_alignment.violations[]` is either resolved (token/component
+  swapped in the inventory) or explicitly waived by the user (logged as such).
+- **After 3d:** UI Element Inventory populated with at least one row per screen in
+  `screens_in_scope[]`. `design.html_path` set OR `mockup-only` flag recorded.
+
+Mark task 2 as `completed`. Update state file status to `specs-confirmed`.
+
+### Canonical example
+
+Feature with 5 screens (`Lista ordini`, `Dettaglio ordine`, `Filtri`, `Onboarding`,
+`Stato pagamento`). Mockups provided for 3 of them.
+
+```
+screens_in_scope:
+  - { name: "Lista ordini",      covered_by_mockups: true,  generated_in_step_3b: false }
+  - { name: "Dettaglio ordine",  covered_by_mockups: true,  generated_in_step_3b: false }
+  - { name: "Filtri",            covered_by_mockups: true,  generated_in_step_3b: false }
+  - { name: "Onboarding",        covered_by_mockups: false, generated_in_step_3b: true  }
+  - { name: "Stato pagamento",   covered_by_mockups: false, generated_in_step_3b: true  }
+```
+
+Result: `ui-design` subskill runs TWICE (one invocation per new screen, each
+producing 3 options). The 3 covered screens skip 3a/3b entirely. The final approval
+gate presents all 5 screens together. `step_3_mode: hybrid`. The PRD links to
+`mockups/` for the 3 covered + `design.html` for the 2 new.

package/framework/.claude/skills/prd/references/validation-phase.md

@@ -6,6 +6,26 @@
 
 Mark task 5 as `in_progress`.
 
+0. **Agent Specialization Audit (runs FIRST — blocks if any failure)** — for each generated child card (epics are skipped):
+
+   a. **`owner_agent` enum check (BLOCKING)** — read the `owner_agent` field. It MUST equal one of:
+      ```
+      coder | ui-expert | plan | visual-designer | motion-expert
+      ```
+      Empty string, missing field, `claude`, or any other value = **BLOCKER**.
+      Message to the user: `"Card <ID> has owner_agent: '<value>' — must be one of {coder, ui-expert, plan, visual-designer, motion-expert}. Fix the card YAML before commit."`
+      Halt the audit. No subsequent checks run on a card that fails this gate.
+
+   b. **UI-only scope heuristic (WARN — soft gate, not blocking)** — for each card with `owner_agent: ui-expert`:
+      - Concatenate `scope.summary`, `requirements[]`, and `acceptance_criteria[]` into one lowercase string.
+      - Grep for logic-marker substrings: `api call`, `endpoint`, `route handler`, `state machine`, `validation logic`, `business rule`, `database`, `migration`, `prisma`, `firestore.collection`, `auth flow`, `token storage`, `webhook`, `cron`.
+      - For each marker hit, log a WARN line in the audit output:
+        `"[UI-SCOPE-WARN] Card <ID> (ui-expert) mentions '<marker>' — review whether logic belongs in a sibling coder card. See backlog-phase.md § Rule B."`
+      - The check is intentionally a soft gate: substrings like "API contract per il mock" or "consumes the auth state from `useAuth()`" are legitimate UI references. The WARN exists to prompt human review, not to block.
+      - Exception (no WARN): the marker appears INSIDE a quoted string that explicitly says "consume", "mock", "contract reference", or "exposed by sibling card" — those are UI cards reading an upstream contract, which is expected.
+
+   **Gate**: every card has `owner_agent` in the enum. WARN entries from check (b) are noted in the audit log; user may accept them after review.
+
 1. **Field Name Audit (runs BEFORE audit agents)** — for each generated card:
 
    a. Verify every `data_fields` entry has `ts_verified: true` OR `status: new` with `schema_ref`.
@@ -16,8 +36,8 @@ Mark task 5 as `in_progress`.
         definition (type, nullable, default, indexing notes).
    c. For cards with `estimated_complexity: LOW`:
       - Verify only that `data_fields` has `ts_verified: true` or `status: new`. No grep needed.
-   d. If card has `firestore_indexes` but NO `data_fields`: log warning —
-      "card touches Firestore (firestore_indexes present) but missing data_fields block."
+   d. If card has `db_indexes` (or legacy `firestore_indexes`) but NO `data_fields`: log warning —
+      "card touches the persistence layer (db_indexes present) but missing data_fields block."
 
    **Gate**: no field with `status: existing | modified` and `ts_verified: false` can proceed.