baldart 3.41.0 → 4.0.0

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

@@ -1,214 +1,18 @@
-# /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>
-```
+# /prd-add — Change Request Phase (redirect stub)
+
+> **This file is NOT the implementation.** It used to carry a hand-maintained,
+> worktree-UNAWARE copy of the Change Request flow that silently diverged from the
+> real skill (it scanned `sessions/` in the main repo and operated on the wrong
+> location for every worktree-isolated PRD session since v3.22.0).
+>
+> The authoritative, worktree-aware Change Request implementation is the **`prd-add`
+> skill**: [`../../prd-add/SKILL.md`](../../prd-add/SKILL.md)
+> (installed as `.claude/skills/prd-add/`).
+
+When a Change Request is triggered — manually (`/prd-add`) or auto-triggered by `/prd`
+discovery when an answer reveals new out-of-scope entities — invoke the `prd-add` skill
+and follow it. The ICIAS impact-analysis protocol it uses is defined once in
+[`impact-analysis.md`](impact-analysis.md) (the canonical SSOT).
+
+Do not re-introduce the CR flow steps here — they live in exactly one place so they
+cannot drift again.

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

@@ -14,28 +14,25 @@ Mark task 3 as `in_progress`.
 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.
+   - If a Canonical Ownership Matrix exists for this project, check the path defined in
+     `.baldart/overlays/prd.md § Canonical Ownership Matrix`; if absent, skip with a note.
    - 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
+     `| Original mockups | ${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.
-   - 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 the persistence layer)**
 
    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.
+   use (once). If the user's answer is not a recognized database type or they
+   answer "I don't know", log a one-line diagnostic, degrade to the universal
+   vocabulary (`entity`/`field`), and proceed — do NOT loop. Persist a valid
+   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"
@@ -60,9 +57,9 @@ Mark task 3 as `in_progress`.
    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).
+      - STOP — do not advance to Section 5 (Data Model).
       - 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 new: add full schema definition in PRD Section 5 (Data Model) and mark `🆕`.
       - If error: correct the name.
 
    **Template `## Schema Verification`** (insert after PRD Acceptance Criteria section):
@@ -89,14 +86,21 @@ Mark task 3 as `in_progress`.
    `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`.
+4. **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.
+5. 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)
+- Strategic rationale (Section 1b — from `## Business Rationale` in state file)
 - Goals / non-goals
 - Personas
 - User stories
@@ -105,18 +109,20 @@ Every PRD MUST include these sections (remove only when genuinely N/A):
     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)
+- API contract changes (ALL endpoints — new routes are NOT exempt — 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
-    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.)
+    with the table empty and a note "Design generated in Step 3 — see design.html".)
+- UI specifications (if applicable — when `## UI Element Inventory` is present in the
+    state file, include the full inventory table verbatim and map each UI element to
+    the requirement it satisfies; when `step_3_mode: skipped` the inventory is absent —
+    populate this section from `mockups/` directory contents or, if no mockups exist,
+    write a placeholder noting "UI design deferred — populate before implementation".
+    Reference `design.html` path when available. 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: one group per persona drawn from
     `identity.audience_segments[]`, plus cross-cutting groups: API, i18n,
@@ -142,7 +148,6 @@ 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
@@ -152,32 +157,37 @@ Before presenting the PRD:
 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.
+**Delegated to the `api-perf-cost-auditor` agent** — `api-perf-gate.md` is its gate
+specification, not an inline checklist the orchestrator runs itself.
+
+### Procedure
+
+1. **Spawn the `api-perf-cost-auditor` agent** via the Task tool (`subagent_type: api-perf-cost-auditor`,
+   `mode: bypassPermissions`). Pass it: (a) the PRD path, (b) the instruction to run the
+   full 5-gate protocol defined in `framework/.claude/skills/prd/references/api-perf-gate.md`
+   as its spec, and (c) the resolved `stack.database` / `stack.deployment` from
+   `baldart.config.yml` for the pricing/cost model. Gate 5 (Text Scan) ALWAYS runs; Gates 1-4
+   (Data Model, Query & Index, Serverless, Caching) run when Gate 5 matches OR the PRD has
+   API/data-model sections — otherwise the agent records the Gate 5 result and notes the 1-4 skip.
+2. **Read the agent's returned findings** (severity-tagged: CRITICAL/HIGH/MEDIUM/LOW).
+3. Apply the findings to the PRD (the orchestrator owns the edits — the agent only reports):
+   - CRITICAL/HIGH: edit the PRD directly (add NFR, modify API contract, add edge case) before
+     the user sees it.
+   - MEDIUM: add to the 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.
+4. If CRITICAL findings were resolved, add a `### Performance-Informed Decisions` subsection to the PRD.
+5. Update state file `## API Performance Gate` (status + findings) so the card-level audit
+   (audit-phase Step 6) can read prior gate verdicts.
 
-**Gate:** all CRITICAL findings resolved in PRD.
+**Gate (BLOCKING):** all CRITICAL findings must be resolved in the PRD before Present & Confirm —
+do NOT present a PRD with an unresolved CRITICAL performance/cost finding.
 
 ## 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).`
+   `**Performance Gate**: N findings integrated in PRD (X critical resolved, Y high as 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.

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

@@ -8,10 +8,17 @@ 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
+Evaluate research need when comprehension reaches **~75%** of non-test
+dimensions covered. The discovery model has **COMPREHENSION_DIMENSION_COUNT = 11**
+dimensions (0–10). Dimension 10 (Test strategy) is the single test dimension;
+the remaining 10 are non-test. The 75% threshold is therefore **8/10 non-test
+dimensions covered**. This allows background research to run while the last
 discovery questions are being asked.
 
+<!-- COMPREHENSION_DIMENSION_COUNT = 11 (dims 0-10); non-test = 10 (dims 0-9);
+     75% threshold = 8 non-test dims covered. Update this constant if discovery-phase.md
+     adds or removes dimensions. -->
+
 ### Complexity Signals
 
 Scan discovery answers and codebase-architect findings for these signals:
@@ -22,14 +29,14 @@ Scan discovery answers and codebase-architect findings for these signals:
 | 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" |
+| S5 | User explicitly signaled uncertainty **about a TECHNICAL or ARCHITECTURAL topic** (not naming/wording/preferences) | "non so come implementare X", "best practice per Y", "come fanno gli altri con Z", "devo capire quale approccio" |
 | 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 |
+| **ALTA** | 2+ signals match, OR S2 (regulatory) matches alone, OR S5 (user uncertainty) matches alone **on a TECHNICAL/ARCHITECTURAL topic** | 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 |
 
@@ -56,18 +63,30 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
 
    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"
+   - S2: "Regulatory requirements for [topic] in {{identity.jurisdiction}} (jurisdiction), implementation checklist"
+     <!-- identity.jurisdiction is not a standard config key; if absent, ASK the user: "Which country/jurisdiction does this feature target?" and persist the answer as a note in the state file. identity.language (BCP-47 tag) is NOT a jurisdiction name. -->
    - 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:**
+2. **Launch `senior-researcher` agent in background via Task tool:**
+
+   > **Background execution constraint**: When run in background, the
+   > senior-researcher agent MUST skip its FIRST MESSAGE TEMPLATE preamble
+   > (clarifying questions / search-plan acknowledgment loop) because no user
+   > is available to respond. The prompt below MUST include the explicit
+   > `BACKGROUND_RUN=true` directive so the agent knows to begin research
+   > immediately. Add this as the first line of the prompt.
+
    ```
-   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
+   Task tool:
+     subagent_type: "senior-researcher"
+     run_in_background: true
+     prompt: |
+       BACKGROUND_RUN=true — skip the FIRST MESSAGE TEMPLATE preamble entirely.
+       Begin research immediately without waiting for acknowledgment.
+
+       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):
@@ -86,8 +105,14 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
        - Key gotchas or anti-patterns to avoid
        - If applicable: regulatory checklist or compliance requirements
 
-       Output a structured report. Be concise but thorough."
-   )
+       OUTPUT CONTRACT (mandatory):
+       Write your complete research report to the file:
+         ${paths.prd_dir}/<slug>/research-<slug>-<session-id>.md
+       where <session-id> is a short UUID you generate at start.
+       Log the exact output path as the FIRST line of your report:
+         RESEARCH_OUTPUT_PATH: <full path>
+       This path is how the PRD orchestrator will read your findings.
+       Be concise but thorough.
    ```
 
 3. **Continue discovery** — do NOT wait for the researcher. Ask remaining
@@ -100,18 +125,39 @@ Trigger as soon as confidence is HIGH (typically at ~75% comprehension).
    Signals: S1 (pattern X), S5 (user said "non so come")
    Topics: [list]
    Status: in-progress
+   LaunchTime: <ISO-8601 timestamp>
+   ResearchOutputPath: (populated by researcher — checked at discovery exit)
    ```
 
 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
+   - **Returned (output file exists)**: process findings (see "Processing Findings" below).
+   - **Not returned yet (output file absent, status in-progress)**: inform user
+     and wait up to **10 minutes** from the launch time recorded in the state file.
+     Display waiting message:
      ```
      Discovery completata. La ricerca sulle best practice e ancora in corso,
      aspetto i risultati prima di procedere.
      ```
+   - **Timed out (output file absent after 10-minute window)**: record
+     `Status: timed-out` in state file and surface:
+     ```
+     La ricerca in background non ha restituito risultati entro il tempo atteso.
+     Opzioni:
+     A) Procedi senza ricerca (i risultati potrebbero essere parziali)
+     B) Riprova a lanciare la ricerca in foreground (l'utente aspetta)
+     ```
+     **STOP.** Wait for user response. If A: mark `Status: timed-out`, proceed.
+     If B: launch foreground (see MEDIUM path below) and set `Status: in-progress`.
+   - **Failed (agent returned error)**: record `Status: failed` in state file and
+     surface the same A/B choice as the timed-out case above.
 
 ### MEDIUM Confidence — Ask User
 
+> **Guard**: Only fire this prompt when state file `Status` is blank/absent (not
+> yet asked). After presenting the question, immediately set `Status: asked` in
+> the state file. This prevents the question from being re-presented on
+> context-compression resume or multi-turn re-evaluation.
+
 At discovery exit (comprehension >= 99%), before proceeding to next phase:
 
 ```
@@ -124,16 +170,28 @@ Vuoi che lanci una ricerca su:
 - <topic 1>
 - <topic 2>
 
-Questo aggiunge ~2-3 minuti ma produce decisioni piu informate.
+Questo aggiunge qualche minuto ma produce decisioni piu informate.
 
 **A)** Si, lancia la ricerca <- consigliato
 **B)** No, procedi direttamente
 ```
 
+<!-- [CALIBRATION-NEEDED: foreground senior-researcher run time — empirically 5-15 min
+     depending on tool latency and search depth; update the user-facing estimate once
+     measured across representative PRD sessions.] -->
+
 **STOP.** Wait for user response.
 
-- If **A**: launch `senior-researcher` in **foreground** (user is waiting).
-  Log in state file. Process findings when returned.
+- If **A**: launch `senior-researcher` via Task tool in **foreground** (user is
+  waiting; do NOT use `run_in_background: true`). Include `BACKGROUND_RUN=false`
+  as the first line of the prompt so the agent follows its normal preamble flow.
+  Log `Status: in-progress` in state file.
+
+  **STOP.** Wait for the foreground Task tool to return. Do NOT continue to the
+  next phase or issue additional tool calls until findings are returned.
+
+  When the Task tool returns: verify the output file exists at the path logged by
+  the researcher, then process findings (see "Processing Findings" below).
 - If **B**: mark research as "skipped" in state file. Proceed to next phase.
 
 ---
@@ -210,7 +268,8 @@ The research phase adds/updates these sections in the state file:
 
 Confidence: ALTA | MEDIA | NESSUNA
 Signals: [matched signals]
-Status: launched | in-progress | completed | skipped
+Status: launched | in-progress | asked | completed | skipped | timed-out | failed
+ResearchOutputPath: <path written by researcher, or empty>
 Topics: [research questions]
 
 ## Research Findings
@@ -224,6 +283,33 @@ Topics: [research questions]
 
 ---
 
+## Context Recovery — Resuming with In-Progress Research
+
+When **Step 0 (Context Recovery)** in `discovery-phase.md` finds `Status: in-progress`
+in the `## Research` section of the state file, apply this resolution logic:
+
+1. **Check for the output file**: read `ResearchOutputPath` from the state file.
+   - If the path is populated and the file exists → researcher already completed.
+     Set `Status: completed`. Process findings normally (see "Processing Findings").
+   - If the path is empty or the file does not exist → researcher did not complete
+     before the previous session ended.
+
+2. **If researcher did not complete**: surface to the user:
+   ```
+   La ricerca precedentemente lanciata non ha prodotto risultati (sessione
+   interrotta). Opzioni:
+   A) Rilancia la ricerca in foreground ora
+   B) Procedi senza ricerca
+   ```
+   **STOP.** Wait for user response. Set `Status: failed` if B, or re-launch
+   foreground (MEDIUM path) if A.
+
+3. **Never silently proceed with `Status: in-progress`** — an unresolved
+   in-progress state means either findings are available and unread, or
+   the background run was lost. Always resolve explicitly.
+
+---
+
 ## Integration with PRD Writing
 
 During Step 4 (PRD Writing), if `## Research Findings` is populated: