baldart 3.40.0 → 4.0.0

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

@@ -8,10 +8,20 @@ Run BEFORE any other step.
    the main repo and scan for an entry with `kind: "docs"` whose `slug` matches
    the feature the user just mentioned (or that you can infer from their
    message — e.g., `/prd-add` for an active PRD).
-   - **Found**: `cd` into the worktree's `path` (save as `$WORKTREE_PATH`),
+   - **Found — worktree path exists on disk**: `cd` into the worktree's `path`
+     (save as `$WORKTREE_PATH`), verify that `pwd` prints the worktree path,
      log "Resuming PRD session in worktree `<path>`", then continue to step 2.
      All subsequent file paths in this skill resolve under `$WORKTREE_PATH`
      (HARD RULE 17).
+   - **Found — worktree path MISSING on disk** (`stale-registry-but-worktree-exists`):
+     the registry entry is present but the directory was deleted (e.g. after a
+     failed `/cw` or disk cleanup). HALT and surface:
+     `WORKTREE_STALE: Registry entry for slug '<slug>' points to '<path>' but
+     that path does not exist on disk. Options: (a) re-create the worktree with
+     the same slug via nw-docs and restore files from git history, (b) start a
+     fresh session (new slug).`
+     **Do NOT proceed** — writing files without a valid working directory will
+     silently corrupt the session.
    - **Not found, but main repo has a stale state file** at
      `${paths.prd_dir}/sessions/*-<slug>-state.md`: this is a pre-v3.22.0 PRD
      session created before the worktree mandate. ASK the user: "Found a
@@ -21,11 +31,23 @@ Run BEFORE any other step.
      files into it. If legacy mode: STOP and warn that parallel sessions
      will pollute `git status`.
    - **Not found and no state file**: fresh session, proceed to Step 1.
-2. With `$WORKTREE_PATH` resolved (or null for fresh sessions), check if
-   `$WORKTREE_PATH/${paths.prd_dir}/sessions/` contains a state file for the
-   current feature.
-3. If found: read it, identify last completed step, resume from next pending step.
-4. If not found: proceed to Step 1.
+2. **Only when `$WORKTREE_PATH` is non-null** (i.e. this is a resume, not a
+   fresh session): check if `$WORKTREE_PATH/${paths.prd_dir}/sessions/` contains
+   a state file for the current feature. If `$WORKTREE_PATH` is null (fresh
+   session), skip this check entirely and proceed to Step 1.
+3. If state file found: read it, identify last completed step and any
+   in-progress sub-state, then apply the **resume dispatch table** below.
+4. If state file not found: proceed to Step 1.
+
+**Resume dispatch table** — after reading the state file, check its status
+field and apply the matching branch before resuming the normal step sequence:
+
+| State file status | Branch |
+|---|---|
+| `mockups.status: requested` AND `mockups.format: pending` | **`mockups pending-input`**: the session was waiting for the user to provide mockup paths/images (Step 1.6.3 STOP). Re-ask: "Stiamo riprendendo la sessione PRD per `<slug>`. Stavi per fornirmi i mockup — in che forma me li passi? (immagini in chat / path locali / archivio .zip)" STOP and wait. |
+| `status: research-in-progress` (background researcher was running) | **`research in-progress`**: log "Resuming — `senior-researcher` was running in background. Attempting to retrieve result." Invoke `senior-researcher` retrieve (or re-launch if result is unavailable). Process findings per the Research Trigger exit check (§ Exit condition) before proceeding. |
+| `status: pending-external-handoff` | **`pending_external_handoff`**: a prior session ended mid-flow waiting on an external dependency (API contract, design handoff, credentials, etc.). Inform the user: "La sessione era in attesa di: `<state.pending_reason>`. Il blocco è stato risolto?" Wait for confirmation before resuming. |
+| Any other status | Resume from the next uncovered step/dimension normally. |
 
 Triggers: session start, context compression, re-invocation of `/prd`, every
 `/prd-add` invocation.
@@ -81,13 +103,15 @@ this is a fresh session (no existing state file).
    - `[PRD] Validazione, commit & merge`
 6. Mark task 1 as `in_progress`.
 7. **Context Loading (MANDATORY):** invoke the context-primer skill (`/cont`) with
-   2-4 keywords extracted from the user's feature description. This launches
-   `codebase-architect` which searches the Obsidian-first LightRAG MCP index,
-   docs, backlog, source code, and git history. The returned context informs all
-   subsequent discovery dimensions. Additionally, run `search_docs` MCP with `mode: "hybrid"` for the
-   feature domain. Use Obsidian hits for concept context, then verify
-   implementation and stateful claims against repo docs/code before carrying
-   them into the PRD.
+   2-4 keywords extracted from the user's feature description and
+   `task_type: "new-feature"` (always explicit — do NOT let context-primer
+   default to `"query"` for domain keywords, which produces a narrower
+   RAG-only context). context-primer internally calls `codebase-architect`
+   which runs `search_docs mode: hybrid`, checks docs, backlog, source code,
+   and git history. The returned context informs all subsequent discovery
+   dimensions. **Do NOT issue a separate `search_docs` call** — context-primer
+   already covers it, and a second call with the same query wastes context
+   window and doubles wiki_log telemetry entries.
 8. Mark clearly irrelevant dimensions as "N/A" with reason
    (e.g., backend-only -> UI impact = N/A).
    If UI impact is N/A, immediately mark task 2 as `completed` ("Skipped — no UI").
@@ -116,7 +140,7 @@ Descrizione: <user's description>
 Contesto:    <one-line summary from context-primer>
 
 Tutti i file del PRD vivono nel worktree — il main repo resta pulito.
-Al termine commit + merge automatico in develop + cleanup worktree, seamless.
+Al termine commit + merge automatico in `git.trunk_branch` + cleanup worktree, seamless.
 (Se in qualunque momento mi dici "non mergiare", mi fermo dopo il commit.)
 
 Ora comincio la fase di **Discovery** — ti faro delle domande per capire bene
@@ -125,9 +149,12 @@ la feature prima di scrivere qualsiasi documento.
 <Progress Bar>
 ```
 
-**Gate:** docs worktree created (registry entry with `kind: "docs"` present)
-AND state file exists on disk inside the worktree AND all tasks created AND
-context loaded.
+**MONITORING SIGNAL (non-blocking):** docs worktree created (registry entry with
+`kind: "docs"` present) AND state file exists on disk inside the worktree AND
+all tasks created AND context loaded. These are logged for observability; they
+do not halt execution. Precondition failures that would surface as a STOP are
+already handled by the BLOCKING gates in points 3 and 4 above — this note is
+a post-completion consistency reminder only, not an additional gate.
 
 **Immediately proceed to Step 1.6** — do NOT stop here. Show the kickoff message
 and ask the mockup intake question in the same turn.
@@ -286,7 +313,8 @@ Build the scope vector from the Kickoff state (Step 1):
 - Verbatim screen names the user mentioned in the initial description.
 - Keywords from `feature_objective_one_sentence` (strip stopwords).
 
-For each candidate, compute a relevance score 0-100:
+For each candidate, compute a relevance score 0-100
+[CALIBRATION-NEEDED: weights below are heuristic; validate against a labeled mockup corpus]:
 - `+40` if any scope keyword appears in the filename (case-insensitive,
   whole-word; for kebab/snake/camelCase, split before matching).
 - `+30` if any scope keyword appears in the HTML `<title>` or `<h1>`.
@@ -296,11 +324,12 @@ For each candidate, compute a relevance score 0-100:
 - `-20` if the filename matches typical non-screen patterns (`icon`, `logo`,
   `favicon`, `thumbnail`, `og-image`, `sitemap`, `manifest`).
 
-Selection threshold: keep candidates with `score ≥ 30` as the auto-selected set.
-If fewer than 3 candidates clear the threshold, lower to `≥ 20` and surface the
-fact. If zero candidates clear `≥ 20`, surface "selezione non automatizzabile —
-ti chiedo di indicarmi a mano quali sono rilevanti" and present the full
-candidate list.
+Selection threshold [CALIBRATION-NEEDED: ≥30/≥20/min-3 are heuristic; no labeled
+dataset validates these cut-offs]: keep candidates with `score ≥ 30` as the
+auto-selected set. If fewer than 3 candidates clear the threshold, lower to
+`≥ 20` and surface the fact. If zero candidates clear `≥ 20`, surface
+"selezione non automatizzabile — ti chiedo di indicarmi a mano quali sono
+rilevanti" and present the full candidate list.
 
 Record per-candidate: `score`, `matched_keywords[]`, `selected: bool`.
 
@@ -388,12 +417,15 @@ nei mockup. Le ambiguità rilevate diventeranno domande mirate.
 
 ### 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
+The `/cont` skill is invoked at **Step 1, point 7** (after the worktree and
+state file are created and macro-tasks are registered, but before the Business
+Rationale Extraction at point 9). It runs synchronously and completes before
+the kickoff output is displayed. The mockup intake question (Step 1.6.1) is
+asked in the same output 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
@@ -406,7 +438,7 @@ update state, send NEXT question, STOP again.
 
 ### Dimension 0 — Business Rationale (ALWAYS FIRST)
 
-If already covered in Step 1.7, skip to dimension 1.
+If already covered in Step 1, point 9 (Business Rationale Extraction), skip to dimension 1.
 
 Otherwise, present this question:
 
@@ -433,9 +465,10 @@ section of the state file. Mark dimension as covered.
 **Precondition:** at least one dimension has status `-` (uncovered).
 
 1. Select next uncovered dimension (in checklist order).
-2. **Use the context already loaded by context-primer (Step 1.5)** to check if
-   the codebase already answers this dimension. The context-primer output includes
-   key docs, key code paths, status, and gotchas — use these to evaluate.
+2. **Use the context already loaded by context-primer (Step 1, point 7)** to
+   check if the codebase already answers this dimension. The context-primer
+   output includes key docs, key code paths, status, and gotchas — use these
+   to evaluate.
    If more specific detail is needed beyond what context-primer provided,
    invoke `codebase-architect` agent (foreground) with a targeted question:
    ```
@@ -488,9 +521,13 @@ section of the state file. Mark dimension as covered.
        Vuoi che avvii un'analisi di impatto (/prd-add) per integrarla nel PRD,
        oppure la notiamo come out-of-scope?`
      - **STOP.** Wait for user response.
-     - If user confirms: read [prd-add-phase.md](prd-add-phase.md) and execute
-       the Change Request flow. After it completes, resume discovery from the
-       next uncovered dimension.
+     - If user confirms: record in the state file under `## Discovery Cursor`
+       the current dimension index (e.g. `cursor: 5`) and the current
+       comprehension score before entering the CR flow. Then invoke the
+       canonical **`prd-add` skill** ([../../prd-add/SKILL.md](../../prd-add/SKILL.md))
+       — the worktree-aware implementation, NOT the `prd-add-phase.md` stub — and
+       execute the Change Request flow. After it completes, read `## Discovery Cursor` from the state
+       file to restore position, then resume 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
@@ -598,8 +635,15 @@ Instead, run the E2E Evaluation Decision Tree and present the result.
 **Result categories:**
 - **NOT NEEDED**: auto-resolve — log reason, mark dimension covered, show inline
   summary, continue to next dimension (no STOP, no user confirmation needed).
-- **RECOMMENDED**: auto-accept (default: yes) — proceed to credential gathering
-  without asking. Show inline: `E2E: RECOMMENDED — accettato automaticamente.`
+- **RECOMMENDED**: present the verdict and ask for explicit confirmation — do
+  NOT auto-accept. Show inline:
+  ```
+  E2E: RECOMMENDED (>3 UI acceptance criteria, no critical-path triggers).
+  Vuoi includerla nel piano di test? (Sì / No)
+  ```
+  **STOP.** If the user confirms: proceed to credential gathering. If the user
+  declines: log `e2e: skipped (user declined RECOMMENDED)`, mark dimension
+  covered, continue.
 - **REQUIRED**: E2E tests MUST be planned. Proceed to credential gathering.
 
 **When E2E is REQUIRED or user accepts RECOMMENDED:**
@@ -662,13 +706,25 @@ Instead, run the E2E Evaluation Decision Tree and present the result.
 > file are intentionally generic. Project-specific defaults live in
 > `.baldart/overlays/prd.md` (consumer-owned, not redistributed).
 
-### Research Trigger (evaluated at ~75% comprehension)
+### Research Trigger (SEMANTIC gate — evaluated at ~75% comprehension)
+[CALIBRATION-NEEDED: "6 non-test dimensions" ≈ 75% of 10 is the trigger point; validate
+threshold against session data — earlier triggers may reduce re-work on complex features.]
 
 When 6+ non-test dimensions are covered, evaluate complexity signals from
-discovery answers and codebase-architect findings. Read
-[research-phase.md](research-phase.md) for full signal list and logic.
-
-**Quick decision:**
+discovery answers and `codebase-architect` findings using the signal table
+S1–S6 below. (The same table also appears in `research-phase.md`; either
+source is authoritative — do NOT issue a separate file-read mid-discovery.)
+
+| ID | Signal | Example |
+|----|--------|---------|
+| S1 | Unfamiliar technical domain | edge caching, payment SCA, WebRTC |
+| S2 | Regulatory / compliance requirement | GDPR, PCI-DSS, PSD2 |
+| S3 | Complex algorithm / heuristic | scoring, ranking, scheduling |
+| S4 | Integration with external system | third-party API, webhook consumer |
+| S5 | User expressed uncertainty | "non so se X sia fattibile" |
+| S6 | Prior art uncertain | no known precedent in codebase |
+
+**SEMANTIC decision:**
 - **2+ signals OR regulatory (S2) OR user uncertainty (S5)** → HIGH confidence
   → launch `senior-researcher` in **background immediately**, continue discovery.
   Update progress bar: `Ricerca: 🔍 in corso (background)`.
@@ -681,7 +737,28 @@ If research launched in background: it runs in parallel with remaining questions
 
 Comprehension >= 99% OR user explicitly says to proceed.
 
-**Before exiting, check research status** (read [research-phase.md](research-phase.md)):
+**Comprehension formula:** `covered / relevant * 100`, where:
+- **`relevant`** = all dimensions whose status is not "N/A".
+- **`covered`** = dimensions whose status is "covered" (any source).
+- Dimension 9 (ISA — auto-scan) and dimension 10 (Test Strategy) ARE included
+  in both `relevant` and `covered` once they resolve. The Research Trigger
+  uses "6+ non-test dimensions" to avoid waiting for dim 10, but the exit
+  formula counts all non-N/A dimensions uniformly.
+
+**Before exiting, resolve mockup gaps (BLOCKING check):**
+Scan `mockup_analysis.screens[].gaps[]` across all screens in the state file.
+Every gap entry must be either:
+- Converted to a Discovery question (already asked and answered), OR
+- Explicitly recorded in the Discovery Log as `"skipped — outside mockup scope"`.
+
+If any gap remains unresolved (neither answered nor skipped), DO NOT proceed
+to Step 3/4. Either ask the gap as the next Discovery question, or ask the
+user: `"Gap '<gap text>' dal mockup non è stato risolto. Lo includo come
+domanda di discovery, oppure lo segniamo come fuori scope?"` **STOP** and wait.
+
+**Before exiting, check research status** (refer to signal table in § Research
+Trigger; read `research-phase.md` only if you need its credential-gathering
+appendix or extended context, not for the signal table):
 1. **HIGH confidence, researcher returned** → process findings, ask follow-up
    questions if gaps found, then exit.
 2. **HIGH confidence, researcher still running** → inform user, wait for result.

package/framework/.claude/skills/prd/references/impact-analysis.md

@@ -1,8 +1,9 @@
 # ICIAS Impact Analysis Protocol
 
 Full protocol for Change Impact Analysis on PRD sessions.
-Based on ProReFiCIA (Etezadi et al. 2025), CodePlan (Bairi et al. 2023),
-and FMEA-adapted scoring.
+[DESIGN-CHOICE: multi-dimensional impact scoring adapted from FMEA risk-priority
+scoring and structural-propagation principles from dependency-graph research.
+Artifact Stakes and threshold bands are heuristics — see Calibration Notes.]
 
 ---
 
@@ -22,10 +23,12 @@ For each of the 10 dimensions, determine:
 
 ### Refinement pass (mandatory)
 
-After initial scan, re-read the change request and check dimensions 4-7
-again (the "middle" of the list — LLMs tend to under-evaluate items in
-the middle of lists, per "lost-in-the-middle" research). Adjust any
-dimension that was initially scored 0 but deserves >= 1 on second look.
+After initial scan, re-read the change request and check dimensions D4–D7
+again (API, UI, Permissions, Edge Cases).
+[DESIGN-CHOICE: explicit second-pass on middle dimensions guards against
+systematic under-evaluation of non-first/non-last items in structured lists.]
+Adjust any dimension that was initially scored 0 but deserves >= 1 on
+second look.
 
 ---
 
@@ -40,8 +43,19 @@ Apply the coupling matrix to find transitive (cascade) impacts.
 3. If edge strength >= 2 AND target dimension has I = 0: mark as cascade impact.
    - Cascade I = max(1, source_I - 1) (degrades by hop)
    - Cascade C = source_C - 1 (min 1) (confidence degrades)
-4. Max hop depth = 2. Do NOT propagate beyond 2 hops.
+   - Note: at min C=1, a two-hop cascade is indistinguishable from a one-hop
+     cascade by confidence alone. The scored verdict (I×C×A) still differentiates
+     them via I degradation across hops.
+4. Max hop depth = 2. Do NOT propagate beyond 2 hops. [CALIBRATION-NEEDED:
+   the 2-hop cap is a heuristic chosen to bound transitive blast radius; a
+   deeper cap may surface real far cascades, a shallower one fewer false ones —
+   validate against observed missed/false cascades after 10–15 change requests.]
+   **Cycle guard**: maintain a visited set of dimension IDs for each traversal
+   path. If the next target is already in the visited set, do NOT propagate —
+   skip that edge entirely. This prevents the D3↔D4 mutual-coupling cycle from
+   overwriting a Phase 1 direct score with a phantom hop-2 cascade score.
 5. If a dimension is reached by both direct and cascade: use direct (higher confidence).
+6. If a dimension is reached by cascade via two different paths: use the higher score.
 
 ### Coupling Matrix (10x10)
 
@@ -81,6 +95,26 @@ D10 TS  0    0    0    0    0    0    0    0    0    -
 
 ---
 
+### Semantic Override Rule (Phase 2 only)
+
+A **semantic override** sets a cascade dimension's I to 0 when explicit
+information in the CR contradicts the computed cascade. Precedence rules:
+
+1. **Only the executing agent may apply a semantic override** — never silently.
+2. **Eligible cases**: the CR contains an explicit, unambiguous statement that
+   negates the cascade (e.g. "no schema changes", "same endpoint contract").
+   Absence of mention does NOT qualify as a semantic override.
+3. **A=3 dimensions (D3 Data Model, D4 API, D9 Integration Surface) require
+   user confirmation** before a semantic override is accepted. Present the
+   computed cascade and the stated reason; receive explicit acknowledgement.
+   Do NOT proceed silently.
+4. **Document every override** in the state file under `## Semantic Overrides`
+   (dimension, original cascade I/C, stated reason, user confirmed: yes/no).
+5. If the override is disputed or unclear: **do not override** — retain the
+   computed cascade value.
+
+---
+
 ## Phase 3 — ICIAS Scoring
 
 For each dimension with I > 0 (direct or cascade):
@@ -101,7 +135,11 @@ For each dimension with I > 0 (direct or cascade):
 | 2 | Probable | Logical deduction, codebase pattern suggests it |
 | 3 | Certain | Explicitly stated in CR, or direct code dependency |
 
-**A = Artifact Stakes** (pre-assigned, fixed per dimension):
+**A = Artifact Stakes** (pre-assigned, fixed per dimension) [CALIBRATION-NEEDED:
+these bands are FMEA-borrowed heuristics; D8 Rollout/Migration at A=1 may
+under-weight data-migration risk in production systems — review after 10–15
+real change requests and recalibrate if D8 produces false-PATCH verdicts]:
+
 | A=3 (High stakes) | A=2 (Medium stakes) | A=1 (Low stakes) |
 |-------------------|---------------------|-------------------|
 | D3 Data Model | D2 User Journey | D1 Target Users |
@@ -109,20 +147,50 @@ For each dimension with I > 0 (direct or cascade):
 | D9 Integration Surface | D6 Permissions | D8 Rollout/Migration |
 | | D10 Test Strategy | |
 
+> **A=1 scoring ceiling**: D1, D7, D8 have a *raw-score* ceiling of 9
+> (3×3×1) → PATCH at most **by score alone**. This is a ceiling of the
+> arithmetic, not a hard cap on the verdict: a structural change on an A=1
+> dimension CAN still reach REDO through the **structural scope exception**
+> in the Verdict thresholds section below (a user-confirmed verdict
+> escalation), so REDO remains reachable for D1, D7, D8.
+
 ### Verdict thresholds
 
+[CALIBRATION-NEEDED: the SKIP/PATCH/REDO score-band cut-points (1–2, 3–9,
+10–27) are FMEA-adapted heuristics, not empirically tuned for PRD CIA; the
+true cut-points that minimise false-PATCH and missed-REDO verdicts should be
+revisited after 10–15 real change requests — see Calibration Notes.]
+
 | Score Range | Verdict | Meaning |
 |-------------|---------|---------|
 | 0 | SKIP | No impact detected |
-| 1–3 | SKIP | Negligible impact, no revision needed |
-| 4–9 | PATCH | Moderate impact, surgical update to affected sections |
+| 1–2 | SKIP | Negligible impact, no revision needed |
+| 3–9 | PATCH | Moderate impact, surgical update to affected sections |
 | 10–27 | REDO | Major impact, phase must be substantially re-executed |
 
+> **Structural scope exception — A=1 dimensions CAN reach REDO.** By raw score
+> alone, D1, D7, D8 top out at 9 (always PATCH). But a structural change
+> (I=3) on one of these dimensions can still demand a full phase
+> re-execution — e.g. fully re-running a rollout/migration plan (D8) or
+> completely re-specifying the edge-case set (D7). When the executing agent
+> judges that the scored PATCH understates the real work, it MUST:
+> 1. Flag a **structural scope exception** (do not silently accept the PATCH).
+> 2. Present the dimension, its score, and the reason the work is REDO-scale
+>    to the user via `AskUserQuestion` (PATCH vs escalate-to-REDO).
+> 3. On explicit user confirmation, **escalate the verdict to REDO** (a
+>    verdict-level override, recorded alongside the score; the raw score is
+>    left intact for calibration). Without confirmation, retain PATCH.
+>
+> This keeps REDO genuinely reachable for A=1 dimensions while preventing a
+> silent over- or under-escalation. [DESIGN-CHOICE: escalation is a
+> user-gated verdict override rather than an A-value bump, so the FMEA score
+> stays comparable across change requests and the override is auditable.]
+
 ### Bias rule
 
 **False negatives are worse than false positives.** When uncertain:
 - Round C up, not down
-- Prefer PATCH over SKIP when on the boundary (score = 3)
+- Score = 3 resolves to PATCH (not SKIP) per the threshold table above
 - Prefer REDO over PATCH only when I = 3 (structural)
 
 ---
@@ -133,8 +201,11 @@ After scoring all dimensions, map to PRD phases:
 
 ### Discovery phase impact
 - ANY dimension with PATCH/REDO → Discovery needs delta update
-- PATCH: update state file checklist, run codebase-architect on affected dims
-- REDO: re-run discovery question loop for affected dims
+- PATCH: update state file checklist; invoke codebase-architect on affected
+  dimensions using the dimensional prompt template defined in
+  `references/discovery-phase.md` Step 2 dimension loop (do not use an
+  unstructured invocation).
+- REDO: re-run discovery question loop for affected dims (see discovery-phase.md)
 
 ### UI Design phase impact
 - D2 Journey REDO OR D5 UI REDO → UI Design REDO
@@ -158,8 +229,18 @@ After scoring all dimensions, map to PRD phases:
 | D9 Integration | 15 (ISA) |
 | D10 Tests | 13 (Test Plan) |
 
+### Integration Surface Analysis (ISA) — always re-scan
+
+**Trigger**: ANY dimension receives verdict PATCH or REDO (regardless of which
+dimension). The ISA re-scan is mandatory and cannot be suppressed by a SKIP
+verdict on D9.
+
+Procedure: run a delta ISA scan focused on the new requirement; merge new
+touchpoints into the existing ISA table; assign new ISA-N IDs.
+
 ### Backlog Cards impact
-- New structural entities (I=3) → new cards needed
+- New verdict REDO on any dimension → evaluate whether new cards are needed
+- New structural entities confirmed (I=3, REDO verdict) → new cards needed
 - Changed acceptance criteria → update existing cards
 - Changed dependencies → update `depends_on` fields
 
@@ -188,11 +269,27 @@ Change type: Addition (new endpoint)
 
 ### Phase 2 — Structural Propagation
 
+Visited set for D4 traversal: {D4}
+
 From D4 (API, I=3):
-- D4→D3 (strength=3): cascade. D3 I=max(1, 3-1)=2, C=2 → but wait,
-  CR says "same schema" → override to I=0. No cascade (semantic override).
-- D4→D9 (strength=3): cascade. D9 I=2, C=2
-- D4→D10 (strength=3): cascade. D10 I=2, C=2
+- D4→D3 (strength=3): cascade candidate. D3 I=max(1,3-1)=2, C=2.
+  CR states "same reservation schema" — **semantic override requested** on
+  A=3 dimension. **Requires user confirmation** (per Semantic Override Rule §3).
+  Confirmed by user → override to I=0. Record in state file `## Semantic
+  Overrides`: D3, cascade I=2/C=2, reason="same schema per CR", confirmed=yes.
+  No cascade on D3.
+- D4→D9 (strength=3): cascade. D9 I=2, C=2. Add D9 to visited.
+- D4→D10 (strength=3): cascade. D10 I=2, C=2. Add D10 to visited.
+
+From D2 (Journey, I=2), visited={D2}:
+- D2→D5 (strength=3): D5 already has direct I=2 (Phase 1) → use direct.
+- D2→D9 (strength=1): below threshold (strength < 2), skip.
+
+From D5 (UI, I=2), visited={D5}:
+- No outgoing strength>=2 edges.
+
+From D7 (Edge Cases, I=2), visited={D7}:
+- D7→D10 (strength=1): below threshold, skip.
 
 ### Phase 3 — ICIAS Score
 
@@ -213,21 +310,28 @@ From D4 (API, I=3):
 
 | Phase | Verdict | Scope |
 |-------|---------|-------|
-| Discovery | PATCH | Update D2, D4, D5, D7, D9, D10 in checklist |
+| Discovery | PATCH | Update D2, D4, D5, D7, D9, D10 in checklist (use discovery-phase.md §Step 2 prompt) |
 | UI Design | REDO | New batch selection flow |
 | PRD | REDO | Sections 4, 6, 7, 10, 13, 15 |
-| Backlog Cards | PATCH | New cards for bulk endpoint + UI; update deps |
+| Backlog Cards | REDO | New cards for bulk endpoint + UI; update deps |
+| ISA | RE-SCAN | Mandatory — REDO/PATCH verdicts present; delta scan for new touchpoints |
 
 ---
 
 ## Calibration Notes
 
-These thresholds are FMEA-adapted heuristics, not empirically validated
-for PRD CIA. After 10-15 real change requests, review:
+These thresholds and A-value bands are FMEA-adapted heuristics, not
+empirically validated for PRD CIA. All bands marked [CALIBRATION-NEEDED]
+are candidates for revision. After 10–15 real change requests, review:
 
 1. Were any SKIPs that should have been PATCHes? → Lower threshold.
 2. Were any REDOs that could have been PATCHes? → Raise threshold.
 3. Did the coupling matrix miss any real cascades? → Add/strengthen edges.
 4. Did the coupling matrix produce false cascades? → Weaken/remove edges.
+5. Were any A=1 dimensions (D1, D7, D8) under-weighted (structural scope
+   exceptions raised)? → Consider raising their A value to 2.
 
-Track calibration data in state file `## Change Requests` section.
+Calibration is the responsibility of the team running `/prd-add` regularly.
+Record observed false negatives and false positives in a project-owned log
+(e.g. a retrospective doc or the project wiki) — impact-analysis.md itself
+is a read-only reference module and cannot write to state files.