baldart 3.40.0 → 4.0.0

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

@@ -10,7 +10,7 @@ cards. Anti-drift by design — rigid step sequence, persistent state, visible p
 
 ## Project Context
 
-**Reads from `baldart.config.yml`:** `paths.prd_dir`, `paths.backlog_dir`, `paths.references_dir`, `paths.design_system`, `paths.ui_guidelines`, `identity.audience_segments`, `identity.language`.
+**Reads from `baldart.config.yml`:** `paths.prd_dir`, `paths.backlog_dir`, `paths.references_dir`, `paths.design_system`, `paths.ui_guidelines`, `paths.metrics` (default `docs/metrics`), `git.trunk_branch`, `git.merge_strategy`, `identity.audience_segments`, `identity.language`.
 **Gated by features:** `features.has_prd_workflow` (skill REFUSES to run when `false`), `features.has_backlog` (Step 5 BLOCKING when `true`), `features.has_design_system` (Step 3 BLOCKING reads), `features.has_adrs` (architectural decisions get logged as ADRs in `paths.adrs_dir`).
 **Overlay:** loads `.baldart/overlays/prd.md` if present — project-specific terminology, card layout overrides, segment names, mandated review gates.
 **On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.
@@ -30,12 +30,12 @@ message. You ask questions, wait for answers, and iterate.
 | 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→CR | Change Request (auto/manual) | [prd-add-phase.md](references/prd-add-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) |
 | 4 | Write PRD | [prd-writing-phase.md](references/prd-writing-phase.md) |
 | 4.5 | API Performance Gate | [api-perf-gate.md](references/api-perf-gate.md) |
-| 4b | Confirm Specs | [prd-writing-phase.md](references/prd-writing-phase.md) |
+| 4b | Confirm Specs (§ "Present and Confirm") | [prd-writing-phase.md](references/prd-writing-phase.md) |
 | 5 | Backlog Cards | [backlog-phase.md](references/backlog-phase.md) |
 | 6 | Quality Audit | [validation-phase.md](references/validation-phase.md) |
 | 7 | Resolution, Commit & Merge | [validation-phase.md](references/validation-phase.md) |
@@ -70,7 +70,8 @@ message. You ask questions, wait for answers, and iterate.
     produces backlog cards MUST organize them as **1 epic + N children**, regardless of N:
     - **Epic**: `${paths.backlog_dir}/FEAT-XXXX-00-<slug>-epic.yml`. Tracker only — no implementation
       work. Contains AC-EPIC list, Definition of Done, business_rationale, scope,
-      scope_boundaries, `execution_strategy` (with parallel_groups computed from the
+      scope_boundaries, `execution_strategy` (with `groups:` — each carrying `level:`
+      and `cards:` — computed from the
       dependency graph), and `documentation_impact` map with `owner_card` per doc.
       `group.parent` = the PRD slug string (NOT a FEAT-ID). `group.sequence: 0`.
       `parallel_group: 0`. `depends_on: []`, `blocks: []`.
@@ -123,8 +124,8 @@ message. You ask questions, wait for answers, and iterate.
     programmatic docs mode — never on the consumer's main checkout. The worktree
     isolates PRD artefacts from other parallel Claude sessions: `git status` on
     the main repo stays clean, accidental stashes / commits / push from sibling
-    `/new` runs cannot pick up PRD files, and the merge back into `develop`
-    becomes a single atomic operation.
+    `/new` runs cannot pick up PRD files, and the merge back into the trunk branch
+    (`git.trunk_branch`) becomes a single atomic operation.
 
     **Why this exists.** Without the worktree, every PRD pollutes the main
     checkout with `${paths.prd_dir}/<slug>/PRD.md`, `${paths.prd_dir}/sessions/...`,
@@ -133,18 +134,25 @@ message. You ask questions, wait for answers, and iterate.
 
     **Lifecycle (deterministic, no opt-in):**
     - **Step 1 (Kickoff)** — after computing `<slug>`, before writing ANY file,
+      capture the main-repo root: run `git rev-parse --show-toplevel` **from the
+      main checkout (before any `cd` into the worktree)** and save the absolute
+      result as `$MAIN` in the state file under `## Worktree` (`main_path`). Then
       call `worktree-manager` programmatic `nw-docs` with `{ slug: <slug> }`.
-      Save the returned `path` as `$WORKTREE_PATH` in the state file under
-      `## Worktree` (path, branch, kind: "docs"). Then `cd "$WORKTREE_PATH"`
+      Save the returned `path` as `$WORKTREE_PATH` in the same `## Worktree`
+      section (path, branch, kind: "docs", main_path). Then `cd "$WORKTREE_PATH"`
       and run `pwd` to verify. From this moment, EVERY file write happens inside
-      the worktree. See [discovery-phase.md](references/discovery-phase.md) § Step 1.
+      the worktree. Both `$MAIN` and `$WORKTREE_PATH` MUST be persisted now so they
+      survive context compaction; the Step 7.5 finalization gate begins with a
+      presence-and-non-empty guard on `$MAIN` and HALTS with a clear message if the
+      field is absent (never operates on an undefined `$MAIN`). See
+      [discovery-phase.md](references/discovery-phase.md) § Step 1.
     - **Step 0 (Context Recovery)** — when resuming a `/prd` or running
       `/prd-add`, scan `.worktrees/registry.json` for entries with
       `kind: "docs"` matching the slug; if found, `cd` into that worktree
       before scanning for state files. See [discovery-phase.md](references/discovery-phase.md) § Step 0.
     - **Step 7 (Commit & Merge)** — commit happens inside the worktree, then
       `worktree-manager` programmatic `mw-docs` is invoked immediately to
-      rebase onto `origin/develop` and land the PRD via the configured
+      rebase onto `origin/<git.trunk_branch>` and land the PRD via the configured
       `git.merge_strategy`. Seamless by default, no confirmation gate (the
       user opted into the full pipeline when they ran `/prd`). If the user
       explicitly says "non mergiare" / "lascia il worktree", honor the
@@ -192,7 +200,7 @@ message. You ask questions, wait for answers, and iterate.
     - `git checkout` / `git switch` / `git branch` on the main repo (worktree-manager Safety Rules).
     - `git stash` anywhere (shared `refs/stash` across worktrees — see Safety Rules in worktree-manager).
     - Writing to the main repo's `${paths.prd_dir}`, `${paths.backlog_dir}`,
-      or `${paths.references_dir}` directly. Only the merge in Step 7 touches `develop`.
+      or `${paths.references_dir}` directly. Only the merge in Step 7 touches the trunk branch (`git.trunk_branch`).
 
     **Exception — when the worktree cannot be created.** If `git worktree add`
     fails (e.g., `.worktrees/` not in `.gitignore`, disk full, repo not a git
@@ -246,18 +254,18 @@ At the END of every message (after all text, before stopping), display:
 
 | # | Fase | Stato |
 |---|------|-------|
-| 1 | Discovery & comprensione | ⬜/🔄/✅ |
 | 1.6 | Mockup intake | ⬜/🔄/✅/⏭️ |
-| 1.5 | Ricerca best practice | ⬜/🔄/✅/⏭️ |
-| 2 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
-| 3 | Conferma specifiche | ⬜/🔄/✅ |
-| 4 | Creazione backlog cards | ⬜/🔄/✅ |
-| 5 | Validazione, commit & merge | ⬜/🔄/✅ |
+| 2 | Discovery & comprensione | ⬜/🔄/✅ |
+| 2.5 | Ricerca best practice | ⬜/🔄/✅/⏭️ |
+| 3 | Design UI & approvazione | ⬜/🔄/✅/⏭️ |
+| 4 | Conferma specifiche | ⬜/🔄/✅ |
+| 5 | Creazione backlog cards | ⬜/🔄/✅ |
+| 6-7 | Validazione, commit & merge | ⬜/🔄/✅ |
 
 Comprensione: X% (N/M dimensioni coperte) — ISA: N punti identificati
 Mockup: ⬜ non chiesto / 🔄 in attesa / ✅ N mockup / ⏭️ nessuno
 Ricerca: ⬜ non valutata / 🔍 in corso (background) / ✅ completata / ⏭️ non necessaria
-Step 3 mode: full / hybrid / skipped (impostato dopo Step 1.6 e refinementato a Step 3)
+Step 3 mode: full / hybrid / mockup-only / skipped (impostato dopo Step 1.6 e refinementato a Step 3)
 Prossimo passo: <what happens next>
 ```
 
@@ -292,7 +300,14 @@ discovery dimensions — avoiding redundant per-dimension agent launches.
 
 ## QUICK REFERENCE — COMPREHENSION DIMENSIONS
 
-The 11 dimensions to cover during discovery:
+**`COMPREHENSION_DIMENSION_COUNT = 11`** (dimensions 0–10) — named constant, SSOT
+defined here. Dimension 10 (Test strategy) is the single test dimension, so
+**non-test = 10** (dimensions 0–9). The research-launch `~75%` trigger references
+this constant by name (`8/10 non-test dimensions covered`) so it fires at a stable
+point — see [research-phase.md](references/research-phase.md) § Trigger Evaluation.
+If you add or remove a dimension below, update the constant in BOTH places.
+
+The 11 dimensions (= `COMPREHENSION_DIMENSION_COUNT`) to cover during discovery:
 
 0. **Business rationale** — why this feature, why now? (business motivation, market signal, expected impact, strategic alignment). Can be resolved from user's initial description or by explicit question (ALWAYS first in discovery loop).
 1. **Target users** — who uses this feature?
@@ -331,33 +346,34 @@ Dimension 10 uses a built-in evaluation tree (see discovery-phase.md).
 
 | # | Fase | Stato |
 |---|------|-------|
-| 1 | Discovery & comprensione | ✅ |
 | 1.6 | Mockup intake | ✅/⏭️ |
-| 1.5 | Ricerca best practice | ✅/⏭️ |
-| 2 | Design UI & approvazione | ✅/⏭️ |
-| 3 | Conferma specifiche | ✅ |
-| 4 | Creazione backlog cards | ✅ |
-| 5 | Validazione, commit & merge | ✅ |
+| 2 | Discovery & comprensione | ✅ |
+| 2.5 | Ricerca best practice | ✅/⏭️ |
+| 3 | Design UI & approvazione | ✅/⏭️ |
+| 4 | Conferma specifiche | ✅ |
+| 5 | Creazione backlog cards | ✅ |
+| 6-7 | Validazione, commit & merge | ✅ |
 
 Comprensione: 100%
 Mockup: ✅ N mockup analizzati / ⏭️ nessuno fornito
 Ricerca: ✅ completata / ⏭️ non necessaria
-Step 3 mode: full / hybrid / skipped
+Step 3 mode: full / hybrid / mockup-only / skipped
 **Pronto per l'implementazione.**
 ```
 
 ---
 
-## Metrics Log (MANDATORY — runs inside Step 7, BEFORE the commit)
+## Metrics Log (MONITORING SIGNAL — non-blocking; runs inside Step 7, BEFORE the commit)
 
-After cards are created and audited (Steps 5-6) and BEFORE the explicit stage in
-validation-phase.md Step 7 point 5, log this PRD run to the skill-runs file.
+After cards are created and audited (Steps 5-6) and BEFORE the explicit stage list in
+validation-phase.md Step 7 point 6 (point 5 is the invocation of this very Metrics Log
+step), log this PRD run to the skill-runs file.
 
 **Location (HARD RULE 17 applies):**
-`$WORKTREE_PATH/docs/metrics/skill-runs.jsonl`
+`$WORKTREE_PATH/${paths.metrics}/skill-runs.jsonl` (`paths.metrics` default: `docs/metrics`)
 
 The file is committed together with the rest of the PRD artefacts in Step 7,
-so it flows into `develop` via `mw-docs` atomically with the PRD.
+so it flows into the trunk branch (`git.trunk_branch`) via `mw-docs` atomically with the PRD.
 
 **Conflict resilience.** JSONL is line-oriented and additive: when two parallel
 PRDs both append a line and one rebases onto the other, the doc-friendly conflict
@@ -367,7 +383,15 @@ exactly the correct semantics). No special handling needed.
 
 **Steps:**
 
-1. Count from the created backlog YAML files:
+> **Telemetry instrument-at-source (W4).** Every field below has a NAMED producer that
+> computes it at this phase — never reconstruct a field by post-hoc LLM parsing of prose,
+> and never add a field with no producer. The record is **assembled fully in memory
+> (including the optional `cost` object) and appended exactly ONCE** — there is no
+> append-then-rewrite of an already-written line.
+
+1. **Assemble the record in memory** (do NOT write to disk yet). The orchestrator at this
+   Step-7 phase is the producer for each field — count them from the created backlog YAML
+   files:
    - `cards_created`: total cards created in this PRD run
    - `ac_coverage_ratio`: total acceptance_criteria count / total user_stories count across all cards
    - `isa_count`: number of ISA items identified (from the progress bar "ISA: N punti")
@@ -375,22 +399,27 @@ exactly the correct semantics). No special handling needed.
    - `has_db_indexes_pct`: % of cards that have a `db_indexes` field (covers any persistence layer; legacy `firestore_indexes` cards count too)
    - `discovery_iterations`: approximate number of Q&A rounds with the user (count AskUserQuestion calls in this session, default 1 if unknown)
 
-2. Append ONE JSON line to `$WORKTREE_PATH/docs/metrics/skill-runs.jsonl`
-   (create the file + parent directory if absent):
+   Base shape (the `cost` key is filled by step 2, then the whole object is appended in step 3):
 
    ```json
    {"ts":"<ISO-8601-UTC>","skill":"prd","run_id":"prd-<slug>","prd_slug":"<slug>","cards_created":0,"ac_coverage_ratio":0.0,"isa_count":0,"has_test_plan_pct":0.0,"has_db_indexes_pct":0.0,"discovery_iterations":1,"prd_path":"${paths.prd_dir}/<slug>/PRD.md"}
    ```
 
-3. **Session token telemetry (ONLY when `stats_enabled: true` in the state file)** — measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
+2. **Session token telemetry — producer for the `cost` field (ONLY when `stats_enabled: true` in the state file)** — measure REAL per-role token + wall-clock cost by post-processing the session transcripts (zero model-token cost — runs in Bash). Invoke:
 
    ```bash
    node .framework/framework/scripts/analyze-session-tokens.js \
-     --skill prd --run-id "prd-<slug>" --out-dir "$WORKTREE_PATH/docs/metrics"
+     --skill prd --run-id "prd-<slug>" --out-dir "$WORKTREE_PATH/${paths.metrics}"
    ```
 
-   The script reads `$CLAUDE_CODE_SESSION_ID` and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — test-only overrides). It writes `$WORKTREE_PATH/docs/metrics/sessions/prd-<slug>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line. Parse that line and add its object under a `"cost"` key on the same JSONL row from step 2; on `stats: SKIPPED (...)` add `"cost":{"skipped":"<reason>"}`. Echo the summary to the user. Add the new `sessions/prd-<slug>.md` file to the explicit stage list too (point 4 below).
+   The script reads `$CLAUDE_CODE_SESSION_ID` and derives the transcript paths itself (do NOT pass `--session` / `--project-dir` — test-only overrides). It writes `$WORKTREE_PATH/${paths.metrics}/sessions/prd-<slug>.md` and prints a summary plus a final `TELEMETRY_JSON=<json>` line. Parse that line and **fold its object into the in-memory record under a `"cost"` key** (do NOT touch the `.jsonl` file — it has not been written yet). On `stats: SKIPPED (...)` set `"cost":{"skipped":"<reason>"}`; when `stats_enabled: false`, omit the `cost` key entirely. Echo the summary to the user. The new `sessions/prd-<slug>.md` file is added to the explicit stage list in step 4.
+
+3. **Append the assembled record ONCE** — write a single JSON line (the fully-built object
+   from steps 1–2) to `$WORKTREE_PATH/${paths.metrics}/skill-runs.jsonl`, creating the file +
+   parent directory if absent. This is a single atomic append — never re-open the line to
+   mutate it afterward. (If a future field needs late enrichment, emit a SEPARATE record
+   keyed by the same `run_id` rather than rewriting this line.)
 
-4. Add the file(s) to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
+4. Add the file(s) (the `.jsonl` plus, when written, `sessions/prd-<slug>.md`) to the explicit stage list in validation-phase.md Step 7 point 6 (the stage list is at point 6; point 5 is the invocation of this very Metrics Log step).
 
 **This step is NON-BLOCKING** — if it fails, do not abort. Log "Metrics Log: SKIPPED" in the progress bar. The PRD merge proceeds regardless. The `-stats` script is itself fail-safe (always exits 0).

package/framework/.claude/skills/prd/assets/card-template.yml

@@ -7,15 +7,12 @@ title: "{{Full descriptive title}}"
 status: TODO
 priority: {{HIGH|MEDIUM|LOW}}
 
-# owner_agent — REQUIRED, no implicit default. One of:
-#   coder            → backend / logic / state / data layer / scripts
-#   ui-expert        → UI implementation (mockup → code, registry-first); UI-ONLY scope
-#   plan             → planning-only card (no code edits)
-#   visual-designer  → static visual assets (illustrations, icons, hero images)
-#   motion-expert    → animation specs (timing, easing, micro-interactions)
+# owner_agent — REQUIRED, no implicit default.
+# Valid values: see the `owner_agent enum` in framework/.claude/agents/REGISTRY.md (the SSOT).
+# Do not maintain a local copy of the enum here — consult REGISTRY.md to avoid drift.
 # The /new orchestrator dispatches by this field (see new/SKILL.md § Agent Routing).
-# Validation phase BLOCKS commit if value is missing or outside this enum.
-owner_agent: <REQUIRED — coder | ui-expert | plan | visual-designer | motion-expert>
+# Validation phase BLOCKS commit if value is missing or outside the REGISTRY enum.
+owner_agent: <REQUIRED — see owner_agent enum in REGISTRY.md>
 execution_mode: local
 
 group:
@@ -24,8 +21,8 @@ group:
 
 git_strategy:
   branch: "feat/{{FEAT-EPIC-ID}}-{{slug}}"
-  base: "develop"
-  target: "develop"
+  base: "{{git.trunk_branch}}"   # resolved from baldart.config.yml git.trunk_branch
+  target: "{{git.trunk_branch}}" # resolved from baldart.config.yml git.trunk_branch
 
 context: |
   {{Background and motivation. Reference PRD sections.}}
@@ -67,7 +64,7 @@ requirements:
 
 # --- Existing Patterns (OPTIONAL — include when card modifies existing code) ---
 # File:line references to code the agent should replicate or extend.
-# "Clear patterns to replicate" is the #1 driver of agent implementation quality (Devin 2025).
+# [DESIGN-CHOICE: explicit patterns to replicate are the highest-signal field for agent implementation quality]
 # Omit for greenfield cards where all files are NEW.
 existing_patterns:
   - description: "{{what pattern to replicate or extend}}"
@@ -111,20 +108,17 @@ estimated_complexity: {{LOW|MEDIUM|HIGH}}
 # review_profile — REQUIRED. Decides the per-card review DEPTH deterministically,
 # at PRD authoring time, so /new READS it instead of re-deriving it at runtime.
 # One field drives BOTH QA depth (Phase 3.5) and the Codex profile (Phase 3.7).
-#   skip     → docs/chore/config or pure-cosmetic cards; no QA/Codex depth needed
-#   light    → bugfix/refactor, ≤3 files, no high-risk areas (NEVER for feature/enhancement)
-#   balanced → default for feature/enhancement, or bugfix/refactor with breadth/risk
-#   deep     → api+data, auth/payment/permission/schema/migration, ≥3 new/modified
-#              data_fields, db_indexes, AC count > 5, or HIGH estimated_complexity
-# Auto-computed by prd-card-writer (§ Review Profile Rules — the SSOT). You MAY
-# override it by hand to force a deeper/shallower review on a specific card.
+# Decision criteria (how skip/light/balanced/deep is chosen) live ONLY in
+# prd-card-writer.md § Rule C — that is the SSOT; do NOT duplicate the criteria here.
+# Auto-computed by prd-card-writer (Rule C). You MAY override by hand to force a
+# deeper/shallower review on a specific card.
 # /new maps skip|light → Codex `light`, balanced|deep → Codex `full` (Phase 3.7);
 # a high-risk path in the actual diff can only ESCALATE the Codex profile, never lower it.
 review_profile: {{skip|light|balanced|deep}}
 
 # Parallelization metadata (auto-computed by /prd backlog phase)
-parallel_group: {{N}}          # Layer di esecuzione: 0 = prima, 1 = dopo layer 0, etc.
-                               # Card nello stesso gruppo possono girare in parallelo
+parallel_group: {{N}}          # Execution layer: 0 = first, 1 = after layer 0, etc.
+                               # Cards in the same group can run in parallel
 
 files_likely_touched:
   - {{path}} ({{NEW|MODIFY}})
@@ -180,7 +174,8 @@ integration_points:
     risk: "{{HIGH|MEDIUM|LOW}}"
 
 # --- Input/Output Examples (OPTIONAL — include for API or data transformation cards) ---
-# Concrete examples disambiguate specs. SWE-bench: 38% of issues are underspecified.
+# Concrete examples disambiguate specs and reduce implementation misinterpretation.
+# [DESIGN-CHOICE: structured input/output prevents agents from inventing contract shapes]
 # Omit for pure UI or documentation-only cards.
 input_output_examples:
   - scenario: "{{scenario name}}"
@@ -226,9 +221,9 @@ data_sources:
     # format: "{{JSONL|YAML|JSON|markdown|binary}}"  # include for file type only
     # note: "{{optional: data shape, why this source}}"
 
-# --- Environment Variables (MANDATORY se la card introduce/modifica env vars — altrimenti []) ---
-# Lista di variabili d'ambiente create, modificate o rimosse da questa card.
-# Il coder usa questo campo per compilare l'entry in ${paths.references_dir}/env-vars.md.
+# --- Environment Variables (MANDATORY if this card introduces/modifies env vars — otherwise []) ---
+# List of environment variables created, modified, or removed by this card.
+# The coder uses this field to populate the entry in ${paths.references_dir}/env-vars.md.
 env_vars:
   - name: "{{VAR_NAME}}"
     action: "{{new|modified|removed}}"
@@ -274,8 +269,9 @@ db_indexes:
 # accepts either name; the writer should prefer db_indexes for new cards.
 firestore_indexes: []  # DEPRECATED in v3.15.0 — use db_indexes instead
 
-documentation_impact:
-  - "{{doc path}} — {{what to update}}"
+documentation_impact:          # same structured shape as the epic's map (children may omit owner_card)
+  - file: "{{doc path}}"
+    action: "{{create | update | delete}} — {{what to update}}"
 
 assumptions:
   - "{{assumption}}"

package/framework/.claude/skills/prd/assets/epic-template.yml

@@ -17,7 +17,7 @@
 #
 # What the epic OWNS:
 #   - AC-EPIC roll-up of PRD acceptance criteria
-#   - execution_strategy with parallel_groups and file_conflicts
+#   - execution_strategy with groups/level and file_conflicts
 #   - documentation_impact map with owner_card per doc
 #   - Strategic business_rationale (full context, not just 2-3 lines)
 # =============================================================================
@@ -44,8 +44,8 @@ group:
 
 git_strategy:
   branch: "feat/{{FEAT-XXXX-00}}-{{slug}}-epic"
-  base: "develop"
-  target: "develop"
+  base: "{{git.trunk_branch}}"   # resolved from baldart.config.yml git.trunk_branch
+  target: "{{git.trunk_branch}}" # resolved from baldart.config.yml git.trunk_branch
 
 context: |
   Epic tracker per la feature "{{Feature Name}}".
@@ -86,7 +86,7 @@ scope_boundaries:
 
 requirements:
   - >
-    Tutte le {{N}} sub-card chiuse con AC verificati e merge in develop.
+    Tutte le {{N}} sub-card chiuse con AC verificati e merge in {{git.trunk_branch}}.
   - >
     Documentation Impact tutte aggiornate (vedi documentation_impact[] sotto).
   - >
@@ -104,7 +104,7 @@ acceptance_criteria:
   - "[ ] [AC-EPIC-5] Entry '{{Feature Name}}' in ${paths.references_dir}/ssot-registry.md."
 
 definition_of_done:
-  - "Tutte le sub-card DONE e mergiate in develop"
+  - "Tutte le sub-card DONE e mergiate in {{git.trunk_branch}}"
   - "PRD §13 test scenarios eseguiti con esito atteso"
   - "Documentation Impact eseguita (vedi documentation_impact[] sotto)"
   - "{{Altri DoD epic-level}}"

package/framework/.claude/skills/prd/assets/state-template.md

@@ -1,10 +1,12 @@
 # PRD Session: {{slug}}
 Created: {{YYYY-MM-DD HH:MM}}
-Status: discovery
+Status: discovery   # discovery | mockups-pending-input | research-in-progress | pending-external-handoff | ui-design | writing | specs-confirmed | backlog | audit | validation | committing | completed | done
 stats_enabled: {{true if invoked with -stats/--stats, else false}}
 
 ## Worktree
 - path: {{absolute worktree path returned by worktree-manager nw-docs}}
+- main_path: {{absolute path of the MAIN repo checkout ($MAIN) — persisted at Step 1 so finalization (validation-phase Step 7.5) never references an undefined var}}
+- trunk_branch: {{resolved git.trunk_branch (default develop)}}
 - branch: prd/{{slug}}
 - kind: docs
 - created_at: {{ISO-8601 UTC}}
@@ -49,11 +51,17 @@ Comprehension: 0% (0/11)
 
 ## Discovery Log
 
+## Discovery Cursor
+
+<!-- Scope-expansion position for resume (see discovery-phase.md Step 0 resume table). -->
+cursor: 0            # index of the last-processed discovery dimension/sub-feature
+comprehension: 0.0   # last computed comprehension fraction (0.0–1.0)
+
 ## Research
 
 Confidence: pending
 Signals: pending
-Status: pending
+Status: pending      # pending | research-in-progress | done | failed | timed-out
 Topics: pending
 
 ## Research Findings
@@ -93,13 +101,27 @@ mockup_analysis.design_system_alignment:
   status: pending                 # aligned | violations | not-applicable
   violations: []
 
-step_3_mode: pending              # full | hybrid | skipped
+step_3_mode: pending              # full | hybrid | skipped | mockup-only
 design.html_path: pending         # path | n/a (mockup-only)
 
 screens_in_scope: []              # [{ name, covered_by_mockups: bool, generated_in_step_3b: bool }]
 
 ui_inventory: []                  # populated by Step 3d
 
+## API Performance Gate
+
+<!-- Populated by api-perf-gate.md (Step 4.5) / api-perf-cost-auditor. Machine-readable
+     so the card-level audit (audit-phase Step 6) can read prior gate verdicts. -->
+status: pending      # pending | pass | warn | block
+findings: []         # [{ gate, severity, summary, resolved: bool }]
+
+## Semantic Overrides
+
+<!-- Populated by ICIAS impact-analysis (impact-analysis.md) when a semantic override
+     adjusts a cascade-derived dimension impact. Each entry records the precedence
+     decision so it is auditable rather than silently applied. -->
+overrides: []        # [{ dimension, cascade_value, override_value, rationale }]
+
 ## Confirmed Specs
 
 ## Backlog Cards