baldart 4.18.0 → 4.19.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to BALDART will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.19.0] - 2026-06-08
+
+**`/prd`: cross-check di completezza della discovery con Codex (shift-left).** Aggiunge un singolo passaggio cross-model **al termine della discovery**, prima del design — il punto a più alto ritorno per Codex in `/prd`. **MINOR** (additivo/opt-in: scatta solo se il companion Codex è risolto a runtime; nessuna chiave `baldart.config.yml` → schema-propagation N/A).
+
+### Added
+
+- **Discovery Completeness Cross-Check (Codex) — `framework/.claude/skills/prd/references/discovery-phase.md`.** Dopo che i gate di uscita esistenti passano (comprehension ≥99% OR user-proceed, mockup-gap risolti, research risolta) e PRIMA di flippare lo status a `ui-design`, un passaggio Codex (`--wait`, pattern di 6.6d) rilegge lo state file di discovery (dimensioni + risposte + Discovery Log) + il brief di kickoff e cerca i **buchi che la formula 99% non può vedere**: domande mai poste, ambiguità latenti, NFR/error-path/edge mancanti, touchpoint d'integrazione. Razionale: la formula misura la copertura delle dimensioni *note*; un modello diverso intercetta i blind spot del questionatore, e catturare un gap di requisiti qui (pre-design) costa molto meno che a Step 6.6d (post-PRD/post-card). Per ogni gap: o diventa la prossima domanda di discovery (one-per-turn) o uno skip esplicito nel Discovery Log (stessa disciplina dei mockup-gap). **Un solo passaggio** (niente loop). **Rispetta l'intent esplicito**: se l'utente ha forzato l'uscita ("proceed"), il check è advisory-only. **Fallback**: Codex assente → skip con log (gate additivo; nessun fallback same-model Claude — annullerebbe la diversità di modello che è l'intero valore del check). Menzione nella flow table di `SKILL.md`.
+
 ## [4.18.0] - 2026-06-08
 
 **Codex come finder a profilo `light` (`/new` + `new2`) + engine Codex opt-in nelle routine cron.** Sposta il carico di review da Claude alla licenza Codex dove la review è read-only e genera finding, mantenendo la diversità di modello (Codex trova, l'agent Claude verifica). **MINOR** (additivo/opt-in con fallback; nessuna rottura install, **nessuna chiave `baldart.config.yml`** → schema-propagation N/A — `review_engine` è schema routine-payload).

package/VERSION

@@ -1 +1 @@
-4.18.0
+4.19.0

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

@@ -39,7 +39,7 @@ message. You ask questions, wait for answers, and iterate.
 | 0 | Context Recovery | [discovery-phase.md](references/discovery-phase.md) |
 | 1 | Kickoff | [discovery-phase.md](references/discovery-phase.md) |
 | 1.6 | Mockup Intake | [discovery-phase.md](references/discovery-phase.md) |
-| 2 | Discovery Question Loop | [discovery-phase.md](references/discovery-phase.md) |
+| 2 | Discovery Question Loop (+ Codex completeness cross-check at exit, v4.19.0) | [discovery-phase.md](references/discovery-phase.md) |
 | 2→CR | Change Request (auto/manual) | the canonical **`prd-add` skill** ([../prd-add/SKILL.md](../prd-add/SKILL.md)) — worktree-aware (`references/prd-add-phase.md` is a redirect stub, not the implementation) |
 | 2.5 | Research (opzionale) | [research-phase.md](references/research-phase.md) |
 | 3 | UI Design (3a-3d) | [ui-design-phase.md](references/ui-design-phase.md) |

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

@@ -928,6 +928,81 @@ appendix or extended context, not for the signal table):
    If yes, launch in foreground and process. If no, mark skipped.
 4. **No research needed** → exit normally.
 
+**Before exiting, run the Discovery Completeness Cross-Check (Codex — since v4.19.0):**
+
+This is the **final, single cross-model sweep** of discovery, run ONLY once all the
+gates above pass (99% comprehension OR user-proceed, mockup gaps resolved, research
+resolved) and BEFORE flipping the status to `ui-design`. Its purpose is the one thing
+the 99% formula structurally cannot do: catch the questions that *should* have been
+asked but weren't. The formula measures coverage of the **predefined** dimensions; a
+different model reading the discovery transcript catches the **questioner's own blind
+spots** — latent ambiguities, missing NFRs, unhandled error/edge paths, data lifecycle,
+permission boundaries, integration touchpoints that no dimension modelled. Catching a
+requirements gap HERE (pre-design) is far cheaper than at the Step 6.6d plan audit
+(post-PRD, post-cards). [DESIGN-CHOICE: cross-model diversity has its highest marginal
+value against the blind spots of the model that conducted the interview]
+
+**Once-per-session guard (MUST — prevents a re-sweep loop).** The exit condition is
+re-evaluated every time the loop tries to exit; addressing a surfaced gap re-enters the
+question loop and then re-reaches this point. So FIRST: if the Discovery Log already
+contains a `discovery-completeness:` entry (from a prior pass this session), **skip this
+block entirely and proceed to exit** — the cross-check is run AT MOST ONCE per discovery
+session, never re-run after its gaps have been processed. Only if no such entry exists do
+you run the sweep below.
+
+**This check is NEVER a hard block** (unlike the mockup-gap check, which gates on physical
+screens). It surfaces gaps and lets the user decide; it never STOPs the exit on its own.
+
+```bash
+SESSION_ID="${SESSION_ID:-$(date +%s%N | md5sum | head -c8)}" && \
+CHECK_FILE="/tmp/codex-discovery-check-<slug>-${SESSION_ID}.md" && \
+CODEX_SCRIPT="$(ls -d ~/.claude/plugins/marketplaces/openai-codex/plugins/codex/scripts/codex-companion.mjs ~/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)" && \
+[ -z "$CODEX_SCRIPT" ] && echo "CODEX_NOT_FOUND" && exit 1; \
+node "$CODEX_SCRIPT" task --wait "
+<task>
+Adversarial DISCOVERY-completeness review — a pre-design quality gate (review-only, DO NOT edit).
+Claude has just finished interviewing the user to scope a feature. Your job is to find the
+questions that SHOULD have been asked but were NOT, and the requirements that remain ambiguous —
+the blind spots of the interviewer. Default to skepticism; assume the interview missed something.
+
+Read the discovery state file below — it contains the dimensions, the answers, the Discovery Log,
+AND the original kickoff brief in its '## Kickoff' section (everything you need is in this one file):
+  ${STATE_FILE_PATH}
+</task>
+
+<attack_surface>
+- Unasked questions: a concern specific to THIS feature that none of the standard dimensions captured.
+- Latent ambiguity: an answer marked 'covered' that is actually vague, shallow, or under-specified.
+- Non-functional requirements never raised: performance budgets, scale/limits, concurrency, auth/permission boundaries, data retention/lifecycle, privacy/PII, observability.
+- Missing error/edge/failure paths (the interview only covered the happy path).
+- Integration touchpoints not discussed: external systems, webhooks, third-party APIs, downstream consumers.
+- Conflicting or unbounded requirements ('all', 'every', no limit) accepted without a boundary.
+</attack_surface>
+
+<grounding_rules>
+Every finding MUST quote the exact dimension/answer (or note its absence) from the state file.
+Do not invent gaps without evidence. Prefer a few strong, high-cost gaps over many weak ones.
+Suppress a finding when the strongest argument that it is already covered is convincing.
+</grounding_rules>
+
+<structured_output_contract>
+For each genuine gap, one line:
+- **Gap title** — what is missing/ambiguous. (Severity: HIGH/MEDIUM/LOW) [Target: <dimension or topic>]
+  > Evidence: exact state-file quote or 'no dimension covers X'
+  > Suggested question: the discovery question that closes it
+End with: 'COMPLETE — no material gaps' if the discovery is genuinely sufficient.
+</structured_output_contract>
+" 2>&1 | tee "$CHECK_FILE"
+```
+
+- `${STATE_FILE_PATH}` = `$WORKTREE_PATH/${paths.prd_dir}/sessions/YYYY-MM-DD-<slug>-state.md` (the single artifact Codex reads — it already embeds the kickoff brief in its `## Kickoff` section, so no separate brief file is passed). **Timeout**: `timeout: 300000` (5 min).
+- **Present + process the findings (ONE pass):**
+  - **Presentation is ONE message** (an explicit, documented exception to HARD RULE 6's one-question-per-turn, exactly like the mockup-gap presentation): show the gaps as a single concise completeness summary, grouped by severity. This summary is a *report*, not a discovery question, so it does not violate the one-question rule.
+  - For each HIGH/MEDIUM gap the user chooses to address, it becomes the **next Discovery question** and follows the **normal per-iteration flow** — asked one-per-turn (HARD RULE 6), its answer folded into the state file, and run through the **Scope Expansion Check** like any other answer (so a gap whose answer reveals new scope routes to `/prd-add` exactly as a normal answer would — no special-casing, no double-trigger). Any gap the user declines → record in the Discovery Log as `"skipped — <reason>"`. LOW gaps are advisory: log them, never block.
+  - **Respect explicit user intent**: if the user reached this point by explicitly saying *proceed* / *basta domande* (the OR-branch of the 99% gate), keep the check **advisory-only** — present the one summary, default to recording every gap as `skipped — user proceeded`, and do NOT re-open the interrogation unless the user opts in. Do not turn an explicit "proceed" into a fresh question loop.
+  - **After processing (whatever the outcome), write ONE `discovery-completeness:` entry to the Discovery Log** (e.g. `discovery-completeness: 2 gaps asked, 1 skipped` / `COMPLETE — no material gaps`). This entry is the once-per-session guard above — its presence means the sweep has run and MUST NOT run again this session.
+- **Fallback (Codex unavailable — `$CHECK_FILE` empty, contains `CODEX_NOT_FOUND`, or holds no parseable findings)**: **skip the cross-check** and log `discovery-completeness: SKIPPED (Codex unavailable)` in the Discovery Log (this also satisfies the once-per-session guard). This gate is **additive** — the 99% formula + mockup + research gates already gate exit. Do NOT fall back to a same-model Claude pass: the entire value here is cross-model diversity, and Claude just conducted the interview (it carries the very blind spot this check exists to catch), so a Claude self-review adds little and is not worth the spawn. Proceed to exit.
+
 When loop exits: mark task 1 as `completed`. Update state file status to
 `ui-design` (or `specs-confirmed` if UI is N/A).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "4.18.0",
+  "version": "4.19.0",
   "description": "Claude Agent Framework - Reusable framework for coordinating AI agents and humans in software projects",
   "bin": {
     "baldart": "./bin/baldart.js"