baldart 5.6.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,104 @@ 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).
 
+## [5.8.0] - 2026-07-06
+
+**Suggested launch plan at the end of `/prd` — waves with a NAME, persisted on the epic card.**
+`/prd` used to close with a progress bar and a bare summary (PRD path, card IDs, branch, PR/SHA)
+but never told you **how to launch `/new`** — one run or several waves, where the boundaries are,
+which engine. You had to reason it out by hand. Now every `/prd` run ends with a mandatory
+**"🚀 Piano di implementazione suggerito"** section, and the plan is **persisted on the epic
+card** so `/new`/`/new2` can, at the end of a subset run, remind you which waves remain to close
+the epic — each wave carries a short, memorable **name** ("Wave 1 · Fondamenta server").
+
+The design was hardened by a two-reviewer adversarial pass that refuted the obvious v1
+(a separate `implementation_plan` block, an `engine` field on the card, a new reference module,
+the mechanical card-writer computing the heuristic). The shipped shape:
+
+- **Drift-free persistence — no new block, no new module.** The wave partition is three OPTIONAL
+  sub-keys (`wave` / `wave_name` / `wave_rationale`) on the EXISTING `execution_strategy.groups[]`
+  entries — the single card-ID partition already consumed by `/new` for parallelism. No parallel
+  `waves[]` array re-listing card IDs (that would drift). Because they are sub-keys of an
+  already-`R` field, the baseline validator never sees them: **no new field-state-matrix row, no
+  migration of legacy epics**. Schema SSOT: `framework/agents/card-schema.md`.
+- **Compute-by-orchestrator / persist-by-writer** (the `provenance.planning_session` split):
+  the `/prd` orchestrator (opus/high) computes the single-run-vs-waves judgment + names + rationale
+  — it needs the discovery context (migration-early, `review_profile: deep` pressure, server↔UI
+  cut) the mechanical `prd-card-writer` never holds — and persists it with a targeted Edit on the
+  epic card. The card-writer emits the keys ONLY when handed them; else it omits them (explicit
+  else branch → no fabrication). Single-run is the default (no wave tags).
+- **Engine + hard rules are render-time, never persisted.** The `/new` vs `/new2` recommendation
+  is computed at render and is **runtime-aware** — `/new2` needs the Workflow tool and is
+  Claude-only, so on Codex the plan recommends `/new` only. A durable, cross-tool artifact must
+  not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- **`/new` + `/new2` remaining-waves.** `/new`'s Step F.6 "Prossimi Passi" and `/new2`'s
+  `buildReport()` "Epic goal" render the remaining waves BY NAME (fallback to the flat card list
+  when the epic has no wave tags — no regression). `/new2` runs fs-less, so the `wave_name` is
+  threaded through `cardGraph` (new `waveName` node field derived by the preflight agent).
+- Project-specific between-wave cautions (migration/deploy gate, compile check, stash) stay in
+  `.baldart/overlays/prd.md` and are surfaced at render-time — no stack names in the base.
+
+No new `baldart.config.yml` key (rides on the existing `execution_strategy` + `features.*`) → the
+schema-change propagation rule does NOT apply. **Codex parity: portable** (runtime-neutral field;
+engine computed at render-time; `/new2` remaining-waves via `cardGraph`).
+
+Skills bumped: `prd` 1.6.1→1.7.0, `new` 2.3.1→2.4.0, `new2` 1.8.1→1.9.0.
+
+## [5.7.0] - 2026-07-06
+
+**Feature-gated skill linking — stop wasting Codex's 2% skill-description budget.** Codex
+reserves ~2% of its context window for skill descriptions; BALDART's ~40 skills alone
+already exceed it (~6.5k tokens), so Codex warns *"Skill descriptions were shortened to fit
+the 2% skills context budget"* and truncates them (degrading skill routing). Until now the
+installer linked EVERY framework skill into a consumer — including ones whose gating
+`features.*` flag is OFF (e.g. the `ds-*` cluster, `i18n`, `graph-align`, `e2e-review`),
+which then merely refuse at runtime: dead weight on the budget. Now a skill is linked only
+when its declared feature is enabled, trimming ~2.5k tokens (~40%) on a typical project
+without design-system/i18n/code-graph/e2e.
+
+- **`requires_feature` frontmatter (SSOT) + `src/utils/skill-gate.js`**: an OPTIONAL
+  `requires_feature: has_x` (string or list = AND) on a skill's `SKILL.md`. Makes
+  machine-readable a dependency the skills already declared in prose (their "Project
+  Context" header) — no second SSOT, same pattern as `version:`/`effort:`. `resolveSkillGate`
+  reads `features.*` **directly** from `baldart.config.yml` (NOT `agent-slots.resolveAgentFlags`,
+  which omits `has_prd_workflow`/`has_e2e_review`) and **fails open** globally (config
+  absent/unreadable → link everything) and per-skill (malformed frontmatter → link that skill).
+- **Applied to BOTH runtimes from one code path** (`mergeSkills` in `src/utils/symlinks.js`):
+  the gate is shared SEMANTICS (which skills are relevant), not runtime mechanics, so Claude
+  (`.claude/skills/`) and Codex (`.agents/skills/`) stay identical by construction. Adds the
+  **prune** direction — a feature flipped off (or a fail-open first install) now removes stale
+  framework symlinks, never touching a user skill dir or a user-override symlink pointing
+  elsewhere.
+- **17 skills gated**: `has_design_system` → ui-design, ui-implement, ds-new, ds-edit,
+  ds-render, design-sync, ds-handoff, motion-design, gamification-design · `has_i18n` → i18n ·
+  `has_code_graph` → graph-align · `has_e2e_review` → e2e-review · `has_prd_workflow` → prd,
+  prd-add · `has_backlog` → new, new2 · `has_wiki_overlay` → capture. The five bootstrap
+  skills (`design-system-init`, `i18n-adopt`, `graphify-bootstrap`, `lsp-bootstrap`,
+  `toolchain-bootstrap`) stay ALWAYS-linked so a feature can always be turned on — then
+  `configure`/`update` re-merge and the cluster appears.
+- **Lifecycle wiring**: `configure` now re-runs `mergeSkills` after writing config (first
+  install linked fail-open before the config existed — this is what actually prunes);
+  `update` already re-merges (prune committed via `BALDART_MANAGED_PATTERNS`); `doctor` gains
+  a non-blocking `reconcile-skills` advisory when a gated-off skill is still linked, and its
+  skill sample-probe no longer samples gatable skills (`prd`/`capture`). `skill-creator`:
+  `quick_validate.py` allow-lists `requires_feature` (it previously HARD-FAILED on unknown
+  keys) + soft-warns unknown flags; `references/skill-structure.md` documents the field.
+  `new2.js` binding-gate now guards on `has_design_system`.
+- **Behaviour change for Claude consumers**: a skill whose feature is off now *disappears*
+  from `.claude/skills/` instead of appearing and refusing at runtime. Mitigated: bootstraps
+  stay visible, and re-enabling the feature (then any merge) brings the cluster back.
+- **Rider — two skill descriptions made `quick_validate`-clean** (pre-existing failures, both
+  among the heaviest so this also shrinks the Codex budget): `ds-edit` description trimmed
+  1080→1014 chars (was over the 1024 max), `ds-handoff` angle-bracket placeholder
+  (`<screens-or-feature>`) rephrased bracket-free — no trigger phrases lost.
+- Verified: unit-level gate partitioning (design_system-off/backlog-on → 15 gated off, `new`
+  linked, bootstrap present), YAML validity of all 17 frontmatters, `quick_validate` PASS.
+- **No new `baldart.config.yml` key** (consumes existing `features.*`) → the schema-change
+  propagation rule does NOT apply; it is skill-frontmatter metadata like `version`/`effort`.
+- **Codex parity: portable** — single semantic filter, both runtimes, install-time only;
+  `requires_feature` is ignored by both skill loaders (they read only name+description, as
+  they already do for `version`/`effort`).
+
 ## [5.6.0] - 2026-07-04
 
 **Outcome-integrity wave (FEAT-0068 post-mortem — mayo, 72.78M token, DONE falso).** Il

package/VERSION

@@ -1 +1 @@
-5.6.0
+5.8.0

package/framework/.claude/agents/prd-card-writer.md

@@ -754,6 +754,29 @@ The consumer (`new/SKILL.md`) reads `execution_strategy.groups[].level` and
 `.cards`. Use these exact keys — `groups`/`level`, not the legacy
 `parallel_groups`/`group`.
 
+**Launch-wave sub-fields (`wave` / `wave_name` / `wave_rationale`) — write ONLY if handed to you.**
+The `/prd` orchestrator may pass a launch-wave partition (a run-sequencing judgment it computes
+AFTER you return the Parallel Execution Map — it needs discovery context you do not hold). When
+and only when the orchestrator hands you these values, add them as optional sub-keys on the
+matching `groups[]` entries:
+
+```yaml
+  groups:
+    - level: 0
+      cards: [FEAT-XXXX-01]
+      description: "Foundation/scaffold"
+      wave: 1                          # only if passed
+      wave_name: "Fondamenta server"   # only if passed
+      wave_rationale: "…"              # only if passed
+```
+
+If the orchestrator does NOT hand you a wave partition, **OMIT all three keys** — do NOT invent a
+wave grouping, a name, or a rationale (a launch judgment fabricated from the card graph alone is
+worse than absent; single-run epics legitimately carry no wave tags). This is the same
+compute-by-orchestrator / persist-by-writer split as `provenance.planning_session`. Schema + the
+render-time derivation live in [`framework/agents/card-schema.md`](../../agents/card-schema.md)
+§ "`execution_strategy.groups[].wave*`".
+
 ## Output Format
 
 **Self-validation BEFORE returning (v5.6.0 — you own your domain's deterministic hygiene).**

package/framework/.claude/skills/capture/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_wiki_overlay` frontmatter — this skill is now linked into a consumer only when `features.has_wiki_overlay` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -2,7 +2,8 @@
 name: capture
 effort: medium
 description: Distilla una sintesi cross-document della conversazione recente in una synthesis page riusabile del wiki overlay (path da `paths.wiki_dir`/syntheses/ in `baldart.config.yml`). Usare quando l'utente invoca `/capture`, dice "capture synthesis", "salva sintesi", "distilla conversazione", "save this as wiki", "questa conversazione in wiki", o quando chiede di trasformare un ragionamento cross-document appena fatto in una pagina stabile. Due modalità — manual (sempre funzionante) e proactive (conditional sui candidati in `.claude/capture-queue/`). Implementa il loop query→wiki file-back di Karpathy.
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_wiki_overlay
 ---
 
 # /capture — Synthesis Capture Skill

package/framework/.claude/skills/design-sync/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/design-sync/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: design-sync
 effort: high
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_design_system
 description: >
   Keep the in-repo design system (the SSOT) and its Claude Design satellite
   "mirror" project in sync — the code→design half of the closed loop. Three modes:

package/framework/.claude/skills/ds-edit/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+- **Description trimmed to pass `quick_validate`**: the `description` was 1080 chars (over the 1024 max); compressed to 1014 without losing any trigger phrase. Also shrinks the Codex skill-description budget.
+
 ## 1.1.0 — 2026-07-02
 
 - **P1 locate hardening.** Reso esplicito che lo step P1 è un lookup deterministico

package/framework/.claude/skills/ds-edit/SKILL.md

@@ -1,23 +1,22 @@
 ---
 name: ds-edit
 effort: medium
-version: 1.1.0
+version: 1.1.1
+requires_feature: has_design_system
 description: >
   Update ONE existing canonical design-system element correctly — the deliberate
   edit twin of /ds-new. Classifies the change (resync the spec to changed source /
-  extend with a new variant or prop / breaking change with migration / re-govern
-  the closed-set role) and runs it end to end: apply the source change (delegated
-  to ui-expert), regenerate the spec via the serializer (HEAD from source, agentic
-  + prose PRESERVED, the canonical template
-  framework/templates/component-spec.template.md filled if a spec is missing),
+  extend with a variant or prop / breaking change + migration / re-govern the
+  closed-set role) and runs it end to end: apply the source change (via ui-expert),
+  regenerate the spec via the serializer (HEAD from source, agentic + prose
+  PRESERVED, the canonical component-spec template filled if a spec is missing),
   re-govern if needed, verify. A THIN orchestrator — delegates every rule to the
   existing SSOTs, never hand-writes a spec HEAD. Use when the user says /ds-edit,
   "aggiorna un componente", "modifica una primitive", "aggiungi una variante",
   "estendi il componente", "resync dello spec", "breaking change su un
-  componente", or when `/prd` confirms a REUSE+VARIANT extension. The pure
-  mechanical doc-resync after a code change is ALREADY automatic (serializer +
-  `DS_COMPONENT_STALE` gate) — this skill is for the DELIBERATE change. Gated on
-  features.has_design_system.
+  componente", or when `/prd` confirms a REUSE+VARIANT extension. The mechanical
+  doc-resync after a code change is ALREADY automatic (`DS_COMPONENT_STALE` gate)
+  — this skill is for the DELIBERATE change. Gated on features.has_design_system.
 ---
 
 # DS Edit — update one existing canonical element

package/framework/.claude/skills/ds-handoff/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.2.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+- **Description made `quick_validate`-clean**: removed the angle-bracket placeholder (`<screens-or-feature>`) the validator rejects, rephrased bracket-free without losing the standalone-invocation trigger.
+
 ## 1.2.0 — 2026-07-02
 
 - **Analysis-profile contract (framework v4.94.0)**: the standalone screen-resolution probe passes `PROFILE=ui` to `codebase-architect` per `framework/agents/analysis-profiles.md`. The Step 3 field-extraction retrieval order is unchanged.

package/framework/.claude/skills/ds-handoff/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ds-handoff
 effort: medium
-version: 1.2.0
+version: 1.2.1
+requires_feature: has_design_system
 description: >
   Produce a FIELD-LEVEL, 1:1, interaction-complete handoff brief for Claude Design
   — every screen's real fields (label, control type, required, validation, default,
@@ -9,7 +10,7 @@ description: >
   data schemas (Zod / TS types / form schemas) via a coverage gate that BLOCKS prompt
   emission when a backed screen's fields are unverified. The single SSOT for the
   Claude Design handoff prompt: `/prd` Step 3.0 Branch B delegates here; usable
-  standalone via `/ds-handoff <screens-or-feature>`. A THIN orchestrator — cites
+  standalone via `/ds-handoff` with a screen list or feature. A THIN orchestrator — cites
   `design-system-protocol.md` (Functional Traceability Gate, Reference Tables) and
   reads `mockup_analysis` as input, never duplicating their rules; reuses existing
   retrieval (code-graph / LSP / codebase-architect / Grep) rather than shipping a

package/framework/.claude/skills/ds-new/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.1.0 — 2026-07-02
 
 - **Reuse-first hardening.** Reso esplicito che lo step 1 reuse-first resta il

package/framework/.claude/skills/ds-new/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ds-new
 effort: medium
-version: 1.1.0
+version: 1.1.1
+requires_feature: has_design_system
 description: >
   Create ONE canonical design-system element — a component OR a token — end to
   end with the full discipline: reuse-first research, (optional) scaffold, then

package/framework/.claude/skills/ds-render/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/ds-render/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ds-render
 effort: medium
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_design_system
 description: >
   Render the design-system primitives in ISOLATION (one component × variant at a
   time) and capture a PNG per entry — the render harness BALDART never had (today

package/framework/.claude/skills/e2e-review/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.3.2 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_e2e_review` frontmatter — this skill is now linked into a consumer only when `features.has_e2e_review` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.3.1 — 2026-07-03
 
 - Boundary pointer: "Not a design generator" ora punta solo a `ui-design`

package/framework/.claude/skills/e2e-review/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: e2e-review
 effort: medium
-version: 1.3.1
+version: 1.3.2
+requires_feature: has_e2e_review
 description: >
   Deterministic, BLOCKING end-to-end review run after a feature is implemented.
   Combines functional E2E (Playwright spec written by `coder`, executed via

package/framework/.claude/skills/gamification-design/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.2 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.1 — 2026-07-03
 
 - Related Skills: `ui-ux-pro-max` (superseded) sostituito con `ui-design` v2

package/framework/.claude/skills/gamification-design/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: gamification-design
 effort: medium
-version: 1.0.1
+version: 1.0.2
+requires_feature: has_design_system
 description: Use when designing or analyzing points systems, reward loops, progression mechanics, engagement features, or loyalty programs. Triggers include "points system," "rewards design," "progression," "engagement loop," "battle pass," "loyalty mechanics," "gamification," or "retention hooks." For B2C customer-facing features in this codebase, this skill invokes the hyper-gamification-designer agent.
 ---
 

package/framework/.claude/skills/graph-align/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_code_graph` frontmatter — this skill is now linked into a consumer only when `features.has_code_graph` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/graph-align/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: graph-align
 effort: medium
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_code_graph
 description: >
   On-demand documentation alignment via the Graphify code knowledge graph.
   Rebuilds the graph offline (graphify update .), then cross-checks graph

package/framework/.claude/skills/i18n/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_i18n` frontmatter — this skill is now linked into a consumer only when `features.has_i18n` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

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

@@ -1,7 +1,8 @@
 ---
 name: i18n
 effort: medium
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_i18n
 description: >
   On-demand internationalization audit + context-aware translation. Audits the
   i18n context registry against the t() calls and native locale files (drift

package/framework/.claude/skills/motion-design/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.0.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_design_system` frontmatter — this skill is now linked into a consumer only when `features.has_design_system` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.0.0 — 2026-07-01
 
 - Baseline: versioning per-skill introdotto al framework v4.82.0.

package/framework/.claude/skills/motion-design/SKILL.md

@@ -10,7 +10,8 @@ description: >
 license: MIT
 metadata:
   author: LottieFiles
-version: 1.0.0
+version: 1.0.1
+requires_feature: has_design_system
 ---
 
 # Motion Design Skill

package/framework/.claude/skills/new/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.4.0 — 2026-07-06
+
+- **Prossime wave per NOME nel messaggio finale.** Il Step F.6 "Prossimi Passi"
+  (`references/final-review.md`) ora è **wave-aware**: legge la partizione di lancio persistita
+  da `/prd` sull'epic card (sotto-campi opzionali `wave` / `wave_name` su
+  `execution_strategy.groups[]`) e, quando presente, mostra le **wave rimanenti per nome**
+  ("Prossime wave: **Wave 2 · Superfici UI**") invece della sola lista card piatta — così, dopo
+  aver implementato un subset (es. `/new FEAT-0069-01..06`), il riepilogo dice cosa resta per
+  chiudere l'epic senza doverlo ricordare. Engine della prossima wave suggerito runtime-aware
+  (Codex → solo `/new`). Richiede un Read esplicito dell'epic card a F.6 (non è in contesto:
+  letto solo transitoriamente in Phase 0). **Fallback grazioso** alla lista card piatta quando
+  l'epic non ha tag wave (single-run / legacy) → nessuna regressione. Schema SSOT:
+  `framework/agents/card-schema.md` § `execution_strategy.groups[].wave*`.
+  - Codex parity: portable (il campo è runtime-neutral; l'engine è calcolato a render-time).
+
+## 2.3.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 2.3.0 — 2026-07-04 (FEAT-0068 post-mortem: integrità dell'esito)
 
 - **Chiusura epic: solo in merge phase, predicato esteso** — `commit.md` c-bis RITIRATO

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

@@ -1,7 +1,8 @@
 ---
 name: new
 effort: medium
-version: 2.3.0
+version: 2.4.0
+requires_feature: has_backlog
 description: >
   Orchestrate a team of specialized agents to implement one or more backlog cards
   end-to-end inside a dedicated worktree, with code review, doc review, QA, and

package/framework/.claude/skills/new/references/final-review.md

@@ -439,7 +439,42 @@ that is a **gate violation**: log it as
      | xargs grep -L "status: DONE"
    ```
 
-   Present the section:
+   **Wave-aware next steps (v5.8.0).** `/prd` may have persisted a **launch-wave partition** on the
+   epic card — optional `wave` / `wave_name` sub-keys on `execution_strategy.groups[]` (schema:
+   `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`"). The epic card is NOT
+   in context here (it was read only transiently in Phase 0) — so **Read the epic card now**
+   (`${paths.backlog_dir}/<EPIC-ID>.yml`) to fetch the wave tags. Then:
+   - **If wave tags exist:** map each remaining not-DONE card to its `wave_name` (via the group whose
+     `.cards` contains it), and render the **remaining WAVES by name** instead of a flat card list — a
+     wave is "rimanente" when ≥1 of its cards is not-DONE. This keeps the thread across runs: the user
+     recognises "Wave 2 · Superfici UI" from the `/prd` plan. Suggest the engine for the NEXT wave
+     runtime-aware (Claude → `/new2` for a high-volume wave, else `/new`; Codex → `/new` only —
+     `/new2` is Claude-only).
+   - **If NO wave tags** (legacy epic / single-run): render the flat "Card rimanenti nell'epic" table
+     exactly as before (backwards-compat, no regression).
+
+   Present the section — WAVE-AWARE form (when wave tags exist):
+
+   ```
+   ## Prossimi Passi
+
+   ### Prossime wave da sviluppare
+   | Wave | Nome | Card rimanenti | Engine suggerito |
+   |------|------|----------------|------------------|
+   | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | /new2 |
+
+   ### Lancio prossima wave (copia e incolla)
+   ```
+   /new2 FEAT-XXXX-07-FEAT-XXXX-13
+   ```
+
+   ### Card completate in questa sessione
+   | Card | Titolo | Commit |
+   |------|--------|--------|
+   | FEAT-XXXX-01 | [title] | abc1234 |
+   ```
+
+   FLAT form (no wave tags — unchanged):
 
    ```
    ## Prossimi Passi

package/framework/.claude/skills/new2/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.9.0 — 2026-07-06
+
+- **Prossime wave per NOME nel report finale (parità con `/new`).** `buildReport()` (`new2.js`)
+  ora, per ogni epic APERTA nella sezione "Epic goal", elenca le **wave rimanenti per nome**
+  dalla partizione di lancio persistita da `/prd` sull'epic. Poiché il workflow gira senza
+  accesso al filesystem, il `wave_name` è **portato via `cardGraph`** (nuovo campo `waveName`
+  sul nodo — l'agente preflight lo deriva dai `execution_strategy.groups[]` dell'epic). Scope
+  onesto: visibili solo le wave le cui card sono NEL BATCH (le wave interamente fuori dal batch
+  non sono caricate). `''` quando l'epic non ha tag wave (single-run / legacy) → nessuna riga.
+  - Codex parity: portable (il campo è runtime-neutral).
+
+## 1.8.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_backlog` frontmatter — this skill is now linked into a consumer only when `features.has_backlog` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.8.0 — 2026-07-04 (FEAT-0068 post-mortem: integrità dell'esito + igiene git)
 
 - **`new2.js`**: step 4b (chiusura epic) RIMOSSO dal commit agent — la chiusura vive

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

@@ -1,7 +1,8 @@
 ---
 name: new2
 effort: high
-version: 1.8.0
+version: 1.9.0
+requires_feature: has_backlog
 description: >
   Workflow-hosted batch engine for /new. Implements one or
   more backlog cards end-to-end by delegating the WHOLE batch to a background

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

@@ -2,6 +2,38 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.7.0 — 2026-07-06
+
+- **Piano di implementazione suggerito nel messaggio finale (sempre).** Il run di `/prd` ora
+  chiude con una sezione **"🚀 Piano di implementazione suggerito"** che dice come lanciare
+  `/new` — unica run vs **wave con NOME**, confini, engine (`/new` vs `/new2`) — invece di
+  lasciare all'utente il compito di ricavarla a mano. La logica del piano è **persistita
+  sull'epic card** così `/new`/`/new2` a fine run possono ricordare quali wave restano.
+  - **Persistenza drift-free:** nessun blocco nuovo — sotto-campi OPZIONALI `wave` / `wave_name`
+    / `wave_rationale` sui `groups[]` esistenti di `execution_strategy` (unica partizione di
+    card-ID; niente `waves[]` parallelo che drifta). Sono sotto-chiavi di un campo già `R` →
+    il baseline validator non le vede, **nessuna riga nuova nella field-state matrix**, epic
+    legacy invariate. Schema SSOT: `framework/agents/card-schema.md`.
+  - **Compute-by-orchestrator / persist-by-writer** (stesso split di `provenance.planning_session`):
+    l'**orchestratore `/prd`** calcola la partizione wave + nomi + rationale (giudizio di lancio
+    che serve il contesto di discovery — migration-early, pressione review `deep`, taglio
+    server/UI) e la persiste con un Edit mirato sull'epic card; il `prd-card-writer` scrive i
+    sotto-campi **solo se gli vengono passati**, altrimenti li omette (ramo else esplicito →
+    niente fabbricazione). Single-run resta il default: nessun tag wave.
+  - **Engine + hard-rule = render-time, non persistiti.** La scelta `/new` vs `/new2` è calcolata
+    a render ed è runtime-aware (Codex → solo `/new`, `/new2` è Claude-only) — un artefatto
+    cross-tool durabile non porta una raccomandazione che un consumer Codex non può eseguire.
+  - **Base generico + overlay:** cautele project-specific tra-wave (migration/deploy gate, compile
+    check, stash) restano in `.baldart/overlays/prd.md`, innestate a render-time.
+  - File: `references/backlog-phase.md` (compute+persist), `references/validation-phase.md`
+    (render), `assets/epic-template.yml` (chiavi commentate), `framework/agents/card-schema.md`
+    (schema), `framework/.claude/agents/prd-card-writer.md` (omit-if-not-passed).
+  - Codex parity: portable (campo runtime-neutral; engine calcolato a render-time).
+
+## 1.6.1 — 2026-07-06
+
+- **Feature-gate**: added `requires_feature: has_prd_workflow` frontmatter — this skill is now linked into a consumer only when `features.has_prd_workflow` is enabled (it already refused at runtime otherwise). Trims Codex's ~2% skill-description budget on projects without the feature. Install-time gate, portable across Claude + Codex.
+
 ## 1.6.0 — 2026-07-04 (FEAT-0068 post-mortem: il root cause era qui)
 
 - **ISA "UI ROLE FAMILY (registry-first)"** (`discovery-phase.md` Dimension 9, gated su

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

@@ -1,7 +1,8 @@
 ---
 name: prd
 effort: high
-version: 1.6.0
+version: 1.7.0
+requires_feature: has_prd_workflow
 description: "Structured PRD creation skill. Use when the user says /prd, 'crea un prd', 'nuova funzionalita', 'pianifica feature', or wants to plan a new feature end-to-end. Also handles /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint' for change requests on active PRD sessions — runs ICIAS impact analysis to determine which phases need SKIP/PATCH/REDO. Produces PRD + UI design + backlog cards, all validated and committed. Multi-turn conversation: asks questions, waits for answers, iterates through discovery, design, spec writing, card creation, and validation phases."
 ---
 

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

@@ -135,6 +135,12 @@ execution_strategy:
     - level: 0
       cards: [{{FEAT-XXXX-01}}]
       rationale: "{{foundation / first dependency layer}}"
+      # Optional launch-wave tags — written by the /prd ORCHESTRATOR only (not the card-writer),
+      # and only when the epic is launched across multiple /new runs. Omit entirely for
+      # single-run epics. Schema: agents/card-schema.md § execution_strategy.groups[].wave*
+      # wave: 1
+      # wave_name: "{{Fondamenta server}}"
+      # wave_rationale: "{{migration + config + resolver + enforcement server}}"
     - level: 1
       cards: [{{FEAT-XXXX-02}}, {{FEAT-XXXX-03}}]
       rationale: "{{parallel after L0}}"