baldart 3.6.2

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

@@ -0,0 +1,214 @@
+# /prd-add — Change Request Phase
+
+Add a new requirement to an existing PRD session. Uses the ICIAS protocol
+(Impact-Confidence-Artifact Stakes) to determine which phases and artifacts
+need revision, then executes only the affected ones.
+
+## Trigger modes
+
+### 1. Manual invocation
+
+User types `/prd-add <description>` or `/prd-add` (then describes the change).
+
+### 2. Auto-trigger from /prd discovery
+
+During `/prd` Step 2 (Discovery Question Loop), if the user's answer reveals
+a new sub-feature or structural requirement NOT covered by the original feature
+description, the `/prd` skill invokes `/prd-add` automatically.
+
+Detection signal: the user's answer introduces NEW entities (endpoints, collections,
+pages, roles, flows) that were not part of the original feature scope.
+
+---
+
+## Execution model
+
+Sequential, single-turn analysis + selective multi-turn re-execution.
+
+| Step | Phase | Description |
+|------|-------|-------------|
+| 0 | Session Locate | Find active PRD state file |
+| 1 | Intake | Capture and classify change request |
+| 2 | Impact Analysis | ICIAS protocol (3 phases) |
+| 3 | Verdict | Present impact matrix, ask confirmation |
+| 4 | Selective Execution | Re-run only PATCH/REDO phases |
+| 5 | Delta Commit | Commit changes with `[PRD-ADD]` prefix |
+
+---
+
+## Hard rules
+
+1. NEVER start from scratch. Always build on the existing PRD session.
+2. Read the state file and PRD before any analysis.
+3. Follow ICIAS protocol exactly — read [impact-analysis.md](impact-analysis.md).
+4. Present verdict BEFORE executing changes. Wait for user confirmation.
+5. When re-running phases, follow the SAME reference files as `/prd` (discovery-phase.md, etc.).
+6. Update the state file with a `## Change Requests` section tracking all CR history.
+7. Commit with format: `[PRD-ADD] <slug>: <brief CR description>`
+8. **Every message MUST end with the CR Progress Bar.**
+
+---
+
+## Step 0 — Session Locate
+
+1. List `${paths.prd_dir}/sessions/` for state files.
+2. If exactly ONE active session (status != `completed`): use it.
+3. If multiple active sessions: ask user which one.
+4. If zero sessions: inform user, suggest `/prd` instead.
+5. Read the state file AND the PRD document (if exists).
+
+---
+
+## Step 1 — Intake
+
+1. If change description provided as argument: use it.
+2. If not: ask the user to describe the change.
+
+**Classify the change type** (from CIA literature):
+
+- **Addition**: new entity (endpoint, collection, page, role, flow)
+- **Modification**: change to existing entity (new field, changed behavior)
+- **Deletion**: removal of planned entity
+
+Record in state file under `## Change Requests`:
+
+```markdown
+### CR-N: <title>
+- Type: Addition | Modification | Deletion
+- Description: <user's description verbatim>
+- Date: YYYY-MM-DD
+- Status: analyzing
+```
+
+**Immediately proceed to Step 2.**
+
+---
+
+## Step 2 — Impact Analysis (ICIAS Protocol)
+
+**Read [impact-analysis.md](impact-analysis.md) for the full protocol.**
+
+Quick summary — 3 phases executed in sequence:
+
+### Phase 1: Semantic Scan
+
+Evaluate each of the 10 dimensions against the change request.
+For each dimension, assign an initial impact assessment (0=none, 1-3=depth).
+
+### Phase 2: Structural Propagation
+
+Apply the coupling matrix to find transitive impacts.
+Max 2 hops, confidence degrades per hop.
+
+### Phase 3: ICIAS Scoring
+
+For each impacted dimension: `Score = I x C x A`
+
+- I = Impact depth (1=cosmetic, 2=logic, 3=structural)
+- C = Confidence (1=inferred, 2=probable, 3=certain)
+- A = Artifact Stakes (pre-assigned per dimension)
+
+Classify: **SKIP** (score <= 3), **PATCH** (4-9), **REDO** (>= 10)
+
+---
+
+## Step 3 — Verdict
+
+Present the impact matrix to the user:
+
+```text
+### Impact Analysis — CR-N: <title>
+
+| # | Dimension | Direct | Cascade | I | C | A | Score | Verdict |
+|---|-----------|--------|---------|---|---|---|-------|---------|
+| D1 | Target users | - | - | 0 | - | 1 | 0 | SKIP |
+| D2 | User journey | yes | - | 2 | 3 | 2 | 12 | REDO |
+| D3 | Data model | - | D4->D3 | 1 | 2 | 3 | 6 | PATCH |
+| ... | ... | ... | ... | ... | ... | ... | ... | ... |
+
+**Fasi da rieseguire:**
+- Discovery: PATCH (D2, D4 da aggiornare)
+- UI Design: REDO (nuovo flow)
+- PRD: PATCH (sezioni 4, 6, 9)
+- Backlog Cards: PATCH (nuove cards + update esistenti)
+
+Vuoi procedere con questa analisi?
+```
+
+**STOP.** Wait for user confirmation.
+
+If user disagrees with any verdict, adjust manually and re-present.
+
+---
+
+## Step 4 — Selective Execution
+
+Execute ONLY phases with PATCH or REDO verdict, in original phase order.
+
+### For Discovery dimensions (PATCH/REDO)
+
+- **PATCH**: Run `codebase-architect` on affected dimensions only.
+  Update state file checklist entries. No user questions unless ambiguous.
+- **REDO**: Full re-discovery for that dimension (same as /prd Step 2 loop
+  but scoped to affected dimensions only). May require user questions.
+
+### For UI Design (PATCH/REDO)
+
+- **PATCH**: Describe changes needed to existing design.html. Ask user
+  if they want a full design refresh or text-only update to PRD.
+- **REDO**: Re-run full UI Design phase (Steps 3a-3d from /prd).
+
+### For PRD (PATCH/REDO)
+
+- **PATCH**: Edit specific PRD sections. Add/modify user stories, API
+  contracts, data model, acceptance criteria as needed. Preserve
+  unchanged sections verbatim.
+- **REDO**: Rewrite major PRD sections (rare — only when change
+  fundamentally alters the feature).
+
+### For Backlog Cards (PATCH/REDO)
+
+- **PATCH**: Create new cards for new work. Update `depends_on` in
+  existing cards if dependencies changed. Do NOT rewrite existing cards
+  unless acceptance criteria changed.
+- **REDO**: Regenerate affected cards via `prd-card-writer` agent.
+  Preserve cards that are unaffected.
+
+### For ISA (always re-scan if any PATCH/REDO exists)
+
+Run a delta ISA scan focused on the new requirement. Merge new
+touchpoints into existing ISA table. Assign new ISA-N IDs.
+
+---
+
+## Step 5 — Delta Commit
+
+1. Update state file:
+   - CR status: `applied`
+   - Update comprehension checklist with changes
+   - Update `## Change Requests` with summary of what was done
+2. Re-run API Performance Gate (Step 4.5) if API/data model changed.
+3. Stage ONLY modified files (explicit names).
+4. Commit: `[PRD-ADD] <slug>: <CR description>`
+
+---
+
+## CR Progress Bar — mandatory on every message
+
+```text
+---
+Change Request: <slug> — CR-N
+
+| # | Fase | Verdict | Stato |
+|---|------|---------|-------|
+| 1 | Intake | - | pending/done |
+| 2 | Impact Analysis | - | pending/running/done |
+| 3 | Verdict & conferma | - | pending/running/done |
+| 4a | Discovery (delta) | SKIP/PATCH/REDO | pending/running/done/skipped |
+| 4b | UI Design (delta) | SKIP/PATCH/REDO | pending/running/done/skipped |
+| 4c | PRD (delta) | SKIP/PATCH/REDO | pending/running/done/skipped |
+| 4d | Backlog Cards (delta) | SKIP/PATCH/REDO | pending/running/done/skipped |
+| 5 | Delta Commit | - | pending/done |
+
+Prossimo passo: <what happens next>
+```

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

@@ -0,0 +1,145 @@
+# PRD Writing Phase (Step 4)
+
+**Precondition:** Discovery complete. UI Design complete or skipped.
+
+Mark task 3 as `in_progress`.
+
+## Write PRD
+
+1. Create directory `docs/prd/<slug>/` if it doesn't exist.
+2. **Obsidian spec note (if present):** if the state file contains `## Obsidian Spec Note`,
+   add a row to the Canonical Sources table in the PRD:
+   `| Obsidian spec | [[Note Name]] |`
+   This preserves traceability from the user's original spec note to the final PRD.
+3. **Resolve canonical sources** before writing:
+   - Read `${paths.references_dir}/ssot-registry.md` to identify the macro feature and any
+     existing canonical docs.
+   - 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.
+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.
+   - Add anti-patterns from research to "Edge cases and failure modes" table.
+   - 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)**
+
+   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).
+
+   **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.
+   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`:
+      - 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 `🆕`.
+      - 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
+
+   ### Collection: {collectionName}
+
+   | Field | Type | Status | Note |
+   |-------|------|--------|------|
+   | `fieldName` | string | ✅ existing | — |
+   | `newField` | string | 🆕 new | schema in Section 3 |
+   | `~~oldField~~` | — | ❌ NOT FOUND | correggi nome |
+
+   ### Blocchi aperti
+   - (nessuno) — oppure lista dei ❌ con azione richiesta
+   ```
+
+   **Nota**: `id`, `createdAt`, `updatedAt` sono universali — non richiedono verifica.
+
+4. Write `docs/prd/<slug>/PRD.md` using the template from `assets/prd-template.md`.
+
+### PRD sections checklist
+
+Every PRD MUST include these sections (remove only when genuinely N/A):
+
+- Problem statement
+- Ratio strategica (Section 1b — from `## Business Rationale` in state file)
+- 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)
+- API contract changes (endpoints, request/response, validation)
+- 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)
+- i18n specification (dictionary keys, locale files)
+- Acceptance criteria (grouped by area: Merchant, Customer, API, i18n)
+- Edge cases and failure modes (table format)
+- Out of scope
+- Dependencies (table with type and status)
+- Pipeline touchpoints (implementation summary table)
+- Integration Surface Map (ISA) — from discovery dimension 9: every existing-code
+  touchpoint that must reference the new feature, with risk levels and card mapping.
+  Every ISA entry MUST map to at least one backlog card.
+- Canonical Sources (macro feature, requirements owner, refs)
+- Implementation References (exact file paths with relevance)
+- Documentation Impact — which reference docs, indexes, registry entries, or ADRs
+  need follow-up updates. Flag ADR-worthy decisions: DB schema changes, API contract
+  changes, new external dependencies, auth changes.
+- Backlog Links — epic/card links (placeholders if cards not yet created)
+- Open questions (only genuine unresolved items)
+
+### Navigation and freshness pass
+
+Before presenting the PRD:
+
+- Verify canonical sources resolve through ssot-registry or valid backlog links.
+- Flag any `REGISTRY_GAP` (feature not yet in ssot-registry).
+- Flag stale shared-hub markers if `Last updated` conflicts with `git log -1`.
+- Remove temp/local/absolute paths from canonical sections.
+
+## Step 4.5 — API Performance Gate
+
+**Precondition:** PRD written (Step 4 complete).
+
+Before presenting the PRD to the user, run the API Performance Gate to catch
+cost and performance anti-patterns while they are still cheap to fix.
+
+**Read [api-perf-gate.md](api-perf-gate.md) for the full 5-gate protocol.**
+
+### Quick procedure
+
+1. **Gate 5 (Text Scan)** — ALWAYS runs. Scan the PRD for keyword red flags
+   (unbounded reads, N+1, fan-out, real-time listeners, etc.).
+2. **If Gate 5 matches OR PRD has API/data model sections** → run Gates 1-4
+   (Data Model, Query & Index, Serverless, Caching).
+3. **If no matches AND no API/data sections** → skip with note in state file.
+4. For each finding:
+   - CRITICAL/HIGH: edit the PRD directly (add NFR, modify API contract, add
+     edge case) before the user sees it.
+   - MEDIUM: add to edge cases table.
+   - LOW: note in state file only.
+5. If CRITICAL findings were resolved, add a `### Performance-Informed Decisions`
+   subsection to the PRD.
+6. Update state file: `## API Performance Gate` with findings count.
+
+**Gate:** all CRITICAL findings resolved in PRD.
+
+## Present and Confirm
+
+1. Update state file `## Confirmed Specs` with FR/NFR lists.
+2. Present structured summary to user: all FR + NFR + visual specs.
+3. If API Performance Gate ran, include a brief summary:
+   `**Performance Gate**: N findings integrati nel PRD (X critical risolti, Y high come NFR).`
+
+**STOP.** Wait for user confirmation. If user requests changes, edit PRD.md and
+re-present. Do NOT proceed to backlog cards without explicit user approval.
+
+**Gate:** explicit user confirmation of specs.
+
+Mark task 3 as `completed`. Update state file status to `cards-writing`.

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

@@ -0,0 +1,216 @@
+# Research Phase (Step 2.5)
+
+Optional phase between Discovery and UI Design. Launches `senior-researcher`
+agent to gather best practices, architectural patterns, or regulatory guidance
+for complex/novel features.
+
+---
+
+## Trigger Evaluation
+
+Evaluate research need when comprehension reaches **~75%** (6/8 non-test
+dimensions covered). This allows background research to run while the last
+discovery questions are being asked.
+
+### Complexity Signals
+
+Scan discovery answers and codebase-architect findings for these signals:
+
+| # | Signal | Example |
+|---|--------|---------|
+| S1 | Algorithm/pattern not in codebase | Recommendation engine, ranking algorithm, scoring system, ML pipeline |
+| S2 | Regulatory/compliance requirement | GDPR consent, PCI-DSS, accessibility WCAG, food allergen regulations |
+| S3 | External service/API never integrated | New payment provider, new SMS gateway, new OCR service |
+| S4 | UX pattern not in the app | Drag-and-drop, real-time collaboration, complex data visualization |
+| S5 | User explicitly signaled uncertainty | "non so come", "best practice", "come fanno gli altri", "devo capire" |
+| S6 | Architecture decision with multiple valid approaches | Polling vs WebSocket, CQRS vs simple CRUD, edge vs server |
+
+### Confidence Classification
+
+| Confidence | Condition | Action |
+|------------|-----------|--------|
+| **ALTA** | 2+ signals match, OR S2 (regulatory) matches alone, OR S5 (user uncertainty) matches alone | Launch research **in background immediately** — no user prompt |
+| **MEDIA** | Exactly 1 non-S2/S5 signal matches | Ask user at discovery exit |
+| **NESSUNA** | No signals match | Skip research, proceed to next phase |
+
+---
+
+## Research Execution
+
+### HIGH Confidence — Background Auto-Launch
+
+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"
+   - 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]"
+
+2. **Launch `senior-researcher` agent in background:**
+   ```
+   Agent(
+     subagent_type: "senior-researcher",
+     run_in_background: true,
+     name: "prd-researcher",
+     prompt: "Research the following topics for a PRD we're writing for feature
+       '<slug>'. Context: <1-2 line feature summary>.
+
+       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)
+       - Key gotchas or anti-patterns to avoid
+       - If applicable: regulatory checklist or compliance requirements
+
+       Output a structured report. Be concise but thorough."
+   )
+   ```
+
+3. **Continue discovery** — do NOT wait for the researcher. Ask remaining
+   questions normally. The researcher runs in parallel.
+
+4. **Log in state file** under `## Research`:
+   ```
+   Research: LAUNCHED (background)
+   Confidence: ALTA
+   Signals: S1 (pattern X), S5 (user said "non so come")
+   Topics: [list]
+   Status: in-progress
+   ```
+
+5. **At discovery exit**, check if researcher has returned:
+   - **Returned**: process findings (see "Processing Findings" below)
+   - **Not returned yet**: inform user, wait for result before proceeding
+     ```
+     Discovery completata. La ricerca sulle best practice e ancora in corso,
+     aspetto i risultati prima di procedere.
+     ```
+
+### MEDIUM Confidence — Ask User
+
+At discovery exit (comprehension >= 99%), before proceeding to next phase:
+
+```
+### Ricerca Best Practice
+
+La feature tocca **<matched signal description>**, un'area dove una ricerca
+sulle best practice potrebbe migliorare la qualita del PRD.
+
+Vuoi che lanci una ricerca su:
+- <topic 1>
+- <topic 2>
+
+Questo aggiunge ~2-3 minuti ma produce decisioni piu informate.
+
+**A)** Si, lancia la ricerca <- consigliato
+**B)** No, procedi direttamente
+```
+
+**STOP.** Wait for user response.
+
+- If **A**: launch `senior-researcher` in **foreground** (user is waiting).
+  Log in state file. Process findings when returned.
+- If **B**: mark research as "skipped" in state file. Proceed to next phase.
+
+---
+
+## Processing Findings
+
+When `senior-researcher` returns:
+
+1. **Store findings** in state file under `## Research Findings`:
+   ```
+   ## Research Findings
+
+   Source: senior-researcher agent (<date>)
+   Topics researched: [list]
+
+   ### Topic 1: <title>
+   **Best practice**: <summary>
+   **Recommended approach**: <for our stack>
+   **Gotchas**: <anti-patterns to avoid>
+   **Sources**: <references>
+
+   ### Topic 2: <title>
+   ...
+   ```
+
+2. **Evaluate if findings reveal gaps** in the discovery:
+   - Do the findings introduce new dimensions or considerations NOT covered
+     by existing discovery answers?
+   - Do the findings contradict or significantly nuance any user decisions?
+   - Do the findings require new data model fields, API endpoints, or UI
+     elements not previously discussed?
+
+3. **If gaps exist — extend discovery:**
+   Present research-driven follow-up questions to the user. Use the same
+   discovery question format (one question, STOP, wait):
+
+   ```
+   ### Domanda Extra (da ricerca) — <topic>
+
+   La ricerca ha evidenziato che [finding summary].
+   Questo impatta la nostra feature perche [impact].
+
+   [Question to resolve the gap]
+
+   **Raccomandazione**: **[Option]** (basata sulla ricerca)
+   > [Rationale from research findings]
+
+   **Alternative**:
+   - **A)** [Research-recommended] <- consigliato (da ricerca)
+   - **B)** [Alternative]
+   ```
+
+   **STOP.** Wait for user response. Update discovery log and state file.
+   Repeat for each gap. These extra questions do NOT count toward the
+   original 9 dimensions — they are logged separately as "research-driven".
+
+4. **If no gaps**: summarize findings briefly and proceed.
+   ```
+   La ricerca conferma l'approccio emerso dalla discovery. Punti chiave:
+   - [key finding 1]
+   - [key finding 2]
+
+   Procedo alla fase successiva.
+   ```
+
+---
+
+## State File Updates
+
+The research phase adds/updates these sections in the state file:
+
+```markdown
+## Research
+
+Confidence: ALTA | MEDIA | NESSUNA
+Signals: [matched signals]
+Status: launched | in-progress | completed | skipped
+Topics: [research questions]
+
+## Research Findings
+
+[populated when researcher returns — see format above]
+
+## Research-Driven Discovery
+
+[any follow-up questions/answers triggered by findings]
+```
+
+---
+
+## Integration with PRD Writing
+
+During Step 4 (PRD Writing), if `## Research Findings` is populated:
+
+- Reference findings in relevant PRD sections (data model, API, edge cases)
+- Cite best practices in the "Rationale" or "Design Decisions" sections
+- Include anti-patterns in the "Edge cases and failure modes" table
+- If regulatory: add compliance checklist as a dedicated PRD section

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

@@ -0,0 +1,61 @@
+# UI Design Phase (Step 3)
+
+Skip entirely if UI impact dimension is N/A. Proceed to PRD Writing Phase.
+
+Mark task 2 as `in_progress`.
+
+## Delegation to `ui-design` Skill
+
+This phase delegates ALL design work to the `ui-design` skill. Do NOT duplicate
+the design workflow here — invoke the skill and follow its output.
+
+### How to invoke
+
+Use the `Skill` tool: `Skill(ui-design)`
+
+The skill handles the full pipeline:
+
+| PRD Step | ui-design Skill Step | What happens |
+|----------|---------------------|--------------|
+| 3a — UI Context Analysis | Steps A + B | Component discovery, context screenshots, codebase analysis |
+| 3b — 3 Design Options | Steps C + D + E | Generate 3 HTML mockups, evaluate with separate agent, open in Safari |
+| 3c — Design Iteration | Step F | User feedback loop with re-evaluation |
+| 3d — Save & Inventory | Step G | Save design.html, extract UI Element Inventory |
+
+### What to pass to the skill
+
+When invoking `ui-design`, ensure it has access to:
+
+- Feature description (from state file `## Feature Description`)
+- All discovery answers relevant to UI (from state file `## Discovery Log`)
+- The `<slug>` for file naming
+- Existing component matches (from registry lookup below)
+
+### Component Registry Lookup (before design)
+
+Before invoking `ui-design`:
+
+1. Read `${paths.references_dir}/component-registry.md`.
+2. From feature description, identify UI elements likely needed (tables, forms, modals, etc.).
+3. Match against registry. Pass results to `ui-design`:
+
+```
+### Existing Components (from component-registry.md)
+REUSE — already exist:
+- [Component] — [path] — [notes]
+
+MISSING — no match found:
+- [element description]
+```
+
+This prevents designing new components when 450+ reusable ones already exist.
+
+### Gates (same as before)
+
+- **After Step 3b:** all 3 polished options open in Safari AND screenshots shown inline.
+  **STOP.** Wait for user to choose.
+- **After Step 3c:** explicit user approval ("confermo", "va bene", "ok").
+- **After Step 3d:** `docs/prd/<slug>/design.html` exists AND `## UI Element Inventory`
+  is populated in the state file with at least 3 elements.
+
+Mark task 2 as `completed`. Update state file status to `specs-confirmed`.