baldart 5.6.0 → 5.8.0

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

@@ -290,6 +290,42 @@ The `prd-card-writer` agent owns the entire card writing pipeline:
 - Presenting results to the user (the agent returns summary, main context displays it)
 - Proceeding to Step 6 (validation phase)
 
+## Launch-wave partition (orchestrator judgment — YOU compute it, not the card-writer)
+
+After the card-writer returns the Parallel Execution Map, **you** (the `/prd` orchestrator)
+decide how the epic should be **launched** across `/new` runs — a judgment the mechanical
+card-writer cannot make because it needs the discovery context you hold (Tier, review-profile
+mix, migration, UI/server split). This is the durable half of the "Piano di implementazione
+suggerito" the final message renders (validation-phase.md § Final output).
+
+**Decide single-run vs waves (scoped — default single-run).** Keep the epic as ONE run unless
+at least one split trigger fires; if none fires, do NOT tag any wave (single-run is the explicit
+else branch — never fabricate a wave grouping just to have one):
+- **Large batch** — many children over several dependency levels (a long single run drifts the
+  trunk mid-batch → merge conflicts instead of fast-forward; keep this rationale generic, do not
+  name a stack).
+- **Migration / schema card present** — land it in an EARLY wave so its migration/deploy gate runs
+  once and later waves build on the real schema.
+- **Review pressure** — many `review_profile: deep` children; splitting keeps the orchestrator
+  context lucid on exactly the cards that need lucid review.
+- **Clear server↔UI cut** — server/data foundation vs UI surfaces is a natural wave boundary
+  (UI/E2E cards exercise the server, so they belong in the later wave).
+- **Cross-domain file conflicts** — `execution_strategy.file_conflicts` that straddle a domain
+  boundary force sequencing.
+
+**Assign waves over the EXISTING groups (one partition, no re-listing of card IDs).** Waves are a
+contiguous grouping of `execution_strategy.groups[]` in `level` order. For each group in a wave,
+set `wave` (1-based, ascending), `wave_name` (a short, unique, human-memorable name derived from
+the wave's dominant domain/role — e.g. "Fondamenta server", "Superfici UI & closer"), and
+`wave_rationale` (one line). Persist them by **editing the epic card** (`backlog/<slug>-00.yml`)
+in the worktree — a targeted Edit adding the three sub-keys to the matching `groups[]` entries.
+Do NOT re-spawn the card-writer; do NOT create a parallel `waves[]` block. Schema:
+`framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`".
+
+**Do NOT persist the engine (`/new` vs `/new2`) or the hard rules** — those are render-time,
+runtime-aware (validation-phase.md § Final output). On a single-run epic, skip this step entirely
+(no wave keys written).
+
 ## Present and Proceed
 
 Present the plan to the user (traceability matrix + parallel execution map) for

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

@@ -410,4 +410,34 @@ A run that prints "local `git.trunk_branch` did not fast-forward, handle the fil
 yourself and then pull" has FAILED Step 7.5 — go back and resolve it before
 printing the summary.
 
+Then, ALWAYS, append the launch plan:
+
+### 🚀 Piano di implementazione suggerito (MANDATORY — always render)
+
+Derive it from the epic card's `execution_strategy` (the wave partition you persisted in
+backlog-phase.md § "Launch-wave partition"); nothing here is recomputed from scratch. Rules +
+schema: `framework/agents/card-schema.md` § "`execution_strategy.groups[].wave*`" (Launch waves).
+
+- **Single-run** (≤1 distinct `wave_name`, e.g. a light-lane 1-child epic): render ONE line —
+  `**Lancia in un'unica run:** \`/new <all card IDs>\`` — no table. Stop here.
+- **Waves** (≥2 distinct `wave_name`): render a table, one row per wave in `wave` order:
+
+  | Wave | Nome | Card | Contenuto |
+  |------|------|------|-----------|
+  | 1 | Fondamenta server | FEAT-XXXX-01…06 | <wave_rationale> |
+  | 2 | Superfici UI & closer | FEAT-XXXX-07…13 | <wave_rationale> |
+
+  Then, below the table:
+  - **Engine (runtime-aware — computed here, never read from the card).** On **Claude** (the
+    `Workflow` tool is available) recommend `/new2` for a high-volume wave (off-context batch, no
+    interactive gates) and `/new` (classic) for a wave that wants human gates (migration / risky
+    review) — a hybrid (`/new` on the risky early wave, `/new2` on the rest) is a valid call. On
+    **Codex** recommend `/new` only — `/new2` needs the `Workflow` tool and does not exist there
+    (`framework/agents/runtime-portability-protocol.md` § "Workflow acceleration"). Give the exact
+    command per wave, e.g. `/new2 FEAT-XXXX-01-FEAT-XXXX-06`.
+  - **Hard rule:** niente altro lavoro in parallelo sugli stessi file tra una wave e l'altra.
+  - **Post-wave gates:** if `.baldart/overlays/prd.md` declares project-specific between-wave
+    cautions (e.g. a migration/deploy gate, a compile check, a stash check), surface them after the
+    relevant wave. Omit this line when the overlay declares none — never invent stack-specific steps.
+
 Display completed Progress Bar.

package/framework/.claude/skills/prd-add/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_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.1.0 — 2026-07-02
 
 - **Analysis-profile contract (framework v4.94.0)**: PATCH-mode re-discovery passes `PROFILE=impact` to `codebase-architect` (blast-radius scoping per `framework/agents/analysis-profiles.md`).

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

@@ -1,7 +1,8 @@
 ---
 name: prd-add
 effort: medium
-version: 1.1.0
+version: 1.1.1
+requires_feature: has_prd_workflow
 description: "Change Request skill for active PRD sessions. Use when the user says /prd-add, 'aggiungi requisito', 'serve anche', 'manca un endpoint', or describes a new requirement that impacts an existing PRD. Also auto-triggered by /prd during discovery when the user's answer reveals a new sub-feature not covered by the original scope. Runs ICIAS impact analysis (semantic scan + structural propagation + scoring) to determine which PRD phases need SKIP/PATCH/REDO, then executes only affected phases."
 ---
 

package/framework/.claude/skills/skill-creator/references/skill-structure.md

@@ -27,13 +27,42 @@ when the skill needs them** — no empty placeholder dirs (that was upstream
 name: <kebab-case>            # matches the directory name
 effort: medium               # low | medium | high | xhigh | max  (effort-protocol.md)
 version: 1.0.0               # the skill's OWN SemVer
+requires_feature: has_x      # OPTIONAL — install-time feature-gate (see below)
 description: >               # triggers + what/when; NO angle brackets
   ...
 ---
 ```
 
-Order: `name` → `effort` → `version` → `description`. `license` / `metadata` are
-tolerated only on imported third-party skills; do not add other keys.
+Order: `name` → `effort` → `version` → (`requires_feature`) → `description`.
+`license` / `metadata` are tolerated only on imported third-party skills; do not
+add other keys.
+
+### `requires_feature` — install-time feature-gate (OPTIONAL)
+
+A skill that is only meaningful when a `baldart.config.yml` `features.*` flag is
+on (and already REFUSES at runtime otherwise) declares that dependency here, so
+the installer links it into a consumer ONLY when the feature is enabled. This
+trims Codex's ~2% skill-description budget on projects that don't use the feature.
+
+```yaml
+requires_feature: has_design_system                 # string  → link iff true
+requires_feature: [has_design_system, has_e2e_review] # list = AND (ALL true)
+```
+
+- **Omit it** for any skill that should always be linked (the default). The five
+  bootstrap skills that ENABLE a feature (`design-system-init`, `i18n-adopt`,
+  `graphify-bootstrap`, `lsp-bootstrap`, `toolchain-bootstrap`) MUST stay ungated
+  — otherwise the feature could never be turned on.
+- The gate is **install-time only** and **portable**: both Claude (`.claude/skills/`)
+  and Codex (`.agents/skills/`) simply see fewer directories. Neither runtime reads
+  the field — it is ignored exactly like `version`/`effort`. Resolution lives in
+  `src/utils/skill-gate.js`; it reads `features.*` directly and **fails open** (a
+  missing config, or a malformed frontmatter, links the skill rather than hiding it).
+- **NOT a `baldart.config.yml` key** — it consumes existing `features.*`, so the
+  schema-change propagation rule does NOT apply. It is skill-frontmatter metadata.
+- **Invariant** (latent, for future Codex `agents/openai.yaml` metadata): a gated
+  skill MUST NOT be declared as a `dependencies:` target of an always-linked skill's
+  `openai.yaml` — pruning the gated skill would leave a dangling dependency.
 
 ## Body headers (in order, when applicable)
 

package/framework/.claude/skills/skill-creator/scripts/quick_validate.py

@@ -39,10 +39,22 @@ def validate_skill(skill_path):
         return False, f"Invalid YAML in frontmatter: {e}"
 
     # Define allowed properties
-    # BALDART additions: `effort` (per-skill reasoning baseline — effort-protocol.md)
-    # and `version` (per-skill SemVer — canonical structure, see references/skill-structure.md).
+    # BALDART additions: `effort` (per-skill reasoning baseline — effort-protocol.md),
+    # `version` (per-skill SemVer — canonical structure, see references/skill-structure.md)
+    # and `requires_feature` (install-time feature-gate — a skill is linked into a
+    # consumer only when this `features.*` flag is on; see references/skill-structure.md
+    # and src/utils/skill-gate.js). All three are OPTIONAL frontmatter metadata,
+    # ignored by the Claude/Codex skill loaders (they only read name+description).
     ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata',
-                          'effort', 'version'}
+                          'effort', 'version', 'requires_feature'}
+
+    # Known feature flags a `requires_feature` value may reference (mirrors the
+    # features.* block of baldart.config.template.yml). Used for a SOFT warning
+    # only — an unknown value is not fatal (fail-open: the gate links the skill).
+    KNOWN_FEATURES = {'has_design_system', 'multi_tenant_theming', 'has_api_docs',
+                      'has_backlog', 'has_adrs', 'has_prd_workflow', 'has_wiki_overlay',
+                      'has_lsp_layer', 'has_code_graph', 'has_e2e_review',
+                      'has_toolchain', 'has_i18n'}
 
     # Check for unexpected properties (excluding nested keys under metadata)
     unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
@@ -90,6 +102,16 @@ def validate_skill(skill_path):
     # `version` + a per-skill CHANGELOG.md are REQUIRED for new skills but WARNED (not
     # hard-failed) here for backwards-compat with skills authored before the convention.
     warnings = []
+    # Soft-validate requires_feature values against the known features.* set.
+    if 'requires_feature' in frontmatter:
+        req = frontmatter['requires_feature']
+        req_list = req if isinstance(req, list) else [req]
+        unknown = [str(f) for f in req_list if str(f) not in KNOWN_FEATURES]
+        if unknown:
+            warnings.append(
+                f"`requires_feature` references unknown flag(s): {', '.join(sorted(unknown))}. "
+                f"The gate fails open (skill still linked). Known: {', '.join(sorted(KNOWN_FEATURES))}"
+            )
     if 'version' not in frontmatter:
         warnings.append("missing `version:` in frontmatter (add `version: 1.0.0`)")
     if 'effort' not in frontmatter:

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

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 2.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.
+
 ## 2.0.0 — 2026-07-03
 
 **The local design studio.** Root-level refactor (framework v5.2.0): the

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

@@ -1,7 +1,8 @@
 ---
 name: ui-design
 effort: medium
-version: 2.0.0
+version: 2.0.1
+requires_feature: has_design_system
 description: "The local design studio — THE framework skill for designing, prototyping and restyling UI directly in the repo (the internal twin of the Claude Design handoff). Produces context-aware, token-compliant HTML mockups in 3 distinct directions, with a locked Design Read, a deterministic anti-slop craft gate and separated generator/evaluator verification. Use when: (1) designing new pages, screens or components, (2) the /prd skill reaches its UI design phase (Step 3), (3) redesigning/restyling existing pages ('rifai la UI', 'migliora il design', 'restyle'), (4) exploring design options ('3 opzioni', 'opzioni di design', 'direzioni estetiche'), (5) prototyping a page/landing/dashboard locally ('prototipo', 'mockup', 'progetta interfaccia', 'design UI'). SUPERSEDES frontend-design (now a router) and ui-ux-pro-max for ALL design/prototyping work. Not for: implementing an already-approved mockup (→ /ui-implement), in-code UI fixes with no design decision (→ ui-expert agent), motion specs (→ /motion-design)."
 ---
 

package/framework/.claude/skills/ui-implement/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 1.1.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.1.1 — 2026-07-02
 
 - Return Contract (SKILL.md): documentati i campi `bindings` + `lane_coverage`/`lanes`

package/framework/.claude/skills/ui-implement/SKILL.md

@@ -1,7 +1,8 @@
 ---
 name: ui-implement
 effort: medium
-version: 1.1.1
+version: 1.1.2
+requires_feature: has_design_system
 description: >
   Implement an ALREADY-APPROVED mockup into the codebase end-to-end and
   self-verify its fidelity. Takes a mockup in any channel — a Claude Design

package/framework/.claude/workflows/new2.js

@@ -219,6 +219,11 @@ const PREFLIGHT_SCHEMA = {
           // Drives the epic-closure blocklist (an epic with open scope residuals/follow-ups must
           // not close) and the Epic goal section of the final report.
           parentEpic: { type: 'string', description: "parent epic id from group.parent or parent: ('' when none)" },
+          // v5.8.0 — the launch-wave this card belongs to, IFF /prd persisted a wave partition on
+          // the epic card (optional wave_name on execution_strategy.groups[] whose .cards includes
+          // this id — schema: agents/card-schema.md § execution_strategy.groups[].wave*). '' when the
+          // epic has no wave tags (single-run / legacy). Drives the "Prossime wave" report line.
+          waveName: { type: 'string', description: "launch wave_name from the epic's execution_strategy.groups[] ('' when none)" },
         },
       },
     },
@@ -305,7 +310,7 @@ try {
       g3Bullet +
       `• G4 card-field validation (setup.md 1b/1c, card-schema.md consumer contract): card missing acceptance_criteria/files_likely_touched/scope → EXCLUDE (excluded[] + reason). \`requirements\` is CONDITIONAL, not an auto-exclude: if it is missing BUT acceptance_criteria + scope are both present and non-empty, FAITHFULLY DERIVE it (a concrete restatement/decomposition of the existing AC + scope — faithful, never inventing new scope) and WRITE it back to the card YAML on disk in ${MAIN}/${paths.backlog_dir || 'backlog'} (F-040: main repo, not the worktree copy; the card artifact is NOT a source/doc file, so this is allowed despite the role boundary), logging \`[BACKFILL] <id>: requirements=<N items, AC+scope-derived>\`. Only EXCLUDE for missing requirements when acceptance_criteria OR scope is ALSO empty (a genuinely thin card). Never HALT for one bad card.\n` +
       `• G5 depends-on: a card whose depends_on names a non-DONE card NOT in this batch → EXCLUDE it AND every in-batch card that transitively depends on it.\n` +
-      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
+      `• cardGraph (REQUIRED, F-021): for every runnable card return { id, dependsOn:[IN-BATCH deps only], ownerAgent (the card's owner_agent; G25 unknown→'coder'), hasMockup (BOOLEAN — true IFF the card BUILDS the mocked UI: links.design_src non-empty, OR links.design non-empty AND (component_bindings non-empty OR files_likely_touched intersects component/style/UI source paths). A bare links.design on a docs/test/meta-only card is a POINTER to the epic's explainer, not a build target — v5.6.0, FEAT-0068: the bare test clamped a docs+ADR card to ui-expert; drives the mockup-first build override — implement.md §6a), parentEpic (the card's parent epic id from group.parent or a top-level parent: field; '' when none — drives the epic-closure blocklist + the Epic goal report section), waveName (v5.8.0 — when the parent epic card carries a launch-wave partition, the wave_name of the execution_strategy.groups[] entry whose .cards includes this id; '' when the epic has no wave tags — single-run/legacy; drives the "Prossime wave" report line), designSrcDir (ABS path of links.design_src / the PRD mockups/_src dir; '' when absent), designHtml (ABS path when links.design is an .html file; '' otherwise), hasBindings (BOOLEAN — non-empty component_bindings), reviewProfile (the card's review_profile; default 'balanced'), policyDeferredACs, alreadyCommitted, alreadyCommittedSha, isEpic (implement.md §6b epic guard: id ends '-00' OR filename ends '-epic.yml' OR group.is_epic:true OR review_profile 'skip' with no requirements), filesLikelyTouched (verbatim from the YAML) }.\n` +
       `• B1/F-026 idempotency (per card, AFTER the worktree exists): set alreadyCommitted:true (+ alreadyCommittedSha) IFF ALL hold: (a) a commit referencing the card id exists in ${TRUNK}..HEAD of the worktree; (b) the card's validation_commands re-run GREEN right now; (c) NO open follow-up card for it exists in ${paths.backlog_dir || 'backlog'}. On a FRESH worktree ${TRUNK}..HEAD is empty → all false, zero extra work.\n` +
       `• F-016 AC↔ownership consistency: for each acceptance_criterion, derive the file(s) it requires editing. If those files are NOT a subset of the card's MAY-EDIT/files_likely_touched → add the AC to policyDeferredACs:[{n,text,owningCard|owningFile,reason}] (it will become ONE follow-up, never a resolve). Do the same for any AC whose remedy is an owner-gated infra action (remote db push / deploy / secret / DNS).\n` +
       (migrationApplied
@@ -634,7 +639,11 @@ async function runCard(cardId, cardPath) {
       : `Phase 1 fallback: the architect specialist was unavailable — do the Phase 1 claim+architect exploration yourself per ${REF}/implement.md and persist the baseline to ${baselinePath} before coding.`
   // T1.A (v4.90.0) — mockup cards: binding-compliance is verified deterministically by the
   // check-bindings.mjs script (ui-implement Step 5b is the SSOT; this is the new2 parallel).
-  const bindingBit = node.hasMockup && node.hasBindings
+  // Guard on has_design_system: component_bindings only exist when a /prd design
+  // phase (which requires the design system) produced them, so absent-DS + bindings
+  // is a malformed hand-authored card — don't emit a gate whose script path could
+  // resolve empty. Mirrors the has_design_system ds-gate guard above.
+  const bindingBit = features.has_design_system && node.hasMockup && node.hasBindings
     ? `\nBINDING GATE (deterministic — ui-implement Step 5b parallel): after building, run \`node "$(ls .claude/skills/ui-implement/scripts/check-bindings.mjs .framework/framework/.claude/skills/ui-implement/scripts/check-bindings.mjs 2>/dev/null | head -1)" --bindings-json '<the card component_bindings as JSON>' --files <your touched implementation files>\`. Exit 3 = a reuse/reuse-variant binding is NOT used in the code: the map is AUTHORITATIVE — fix it before returning (one pass). Include the script's one-line JSON output as bindingCheck in your return.\n`
     : ''
   let impl
@@ -1683,7 +1692,19 @@ function buildReport(o) {
       const epicHigh = residuals.filter((r) => ((graphById[r.card] && graphById[r.card].parentEpic) === e || r.card === e) && (sevRank[residualSeverity(r)] || 0) >= 2)
       if (closedEpics.includes(e) && !closureBlockedEpics.has(e)) L.push(`- **${e}: CHIUSA** (children DONE + AC epic verificati dal merge agent)`)
       else if (closedEpics.includes(e)) L.push(`- **${e}: ⚠️ CHIUSA CONTRO BLOCKLIST (false DONE)** — riaprire: ${epicHigh.length} residuo/i HIGH aperti`)
-      else L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+      else {
+        L.push(`- **${e}: APERTA** — ${reason || (closureBlockedEpics.has(e) ? 'blocklist: residui/follow-up aperti' : 'merge non eseguito o children aperti')}${epicHigh.length ? ` · ${epicHigh.length} residuo/i HIGH` : ''}`)
+        // v5.8.0 — remaining launch waves by NAME (parity with /new final-review F.6). Uses the
+        // waveName threaded through cardGraph (buildReport has no fs access to re-read the epic).
+        // Honest scope: only waves whose cards are IN THIS BATCH are visible — waves entirely
+        // outside the batch aren't loaded, so this reflects the batch, not the whole epic.
+        const openWaves = dedupe(
+          cardGraph
+            .filter((n) => (n.parentEpic || '') === e && n.waveName && (perCardResults.find((r) => r.card === n.id) || {}).status !== 'DONE')
+            .map((n) => n.waveName)
+        )
+        if (openWaves.length) L.push(`  - Prossime wave (batch): ${openWaves.map((w) => `**${w}**`).join(' · ')}`)
+      }
     }
   }
   if (finalSummary) {

package/framework/agents/card-schema.md

@@ -230,6 +230,56 @@ Rules:
 - Omit any sub-field whose session id is unavailable (env var unset) rather than writing a
   placeholder.
 
+### `execution_strategy.groups[].wave*` — launch-wave annotation (epic-only, optional, orchestrator-written)
+
+The epic's `execution_strategy.groups[]` is the **single card-ID partition** consumed by `/new`
+for parallelism (`groups[].level` + `.cards` — the machine schedule). A **launch wave** is a
+coarser, human-facing partition layered ON TOP of those same groups so the user can sequence the
+epic across multiple `/new` runs and refer to each run by a stable NAME. It is expressed as three
+**optional sub-fields on the existing `groups[]` entries** — never a parallel block that re-lists
+card IDs (that would be a second SSOT that drifts from `groups[].cards`):
+
+```yaml
+execution_strategy:
+  recommended_mode: team | sequential      # existing — scheduling shape, runtime-neutral
+  groups:
+    - level: 0
+      cards: [FEAT-0069-01, FEAT-0069-02]   # existing — the ONLY card-ID partition
+      description: "Foundation/scaffold"     # existing
+      wave: 1                                # opt — 1-based wave index (contiguous over groups)
+      wave_name: "Fondamenta server"         # opt — short, unique human NAME for the wave
+      wave_rationale: "migration + config + resolver + enforcement server"  # opt — why this wave
+```
+
+Rules:
+- **Optional (`C`)**, epic-only. They are **sub-keys of `execution_strategy`** (already `R`), NOT
+  top-level fields — the field-state matrix carries **no new row** and the baseline validator (which
+  checks only top-level presence/non-emptiness) never sees them. Legacy epics lack them → no HALT,
+  no migration.
+- **Ownership split (same as [`provenance`](#provenance-session-id-traceability--optional-skill-written)):**
+  the `/prd` **orchestrator** COMPUTES the wave partition + names + rationale (a launch judgment that
+  needs discovery context — migration-early, review-`deep` pressure, server↔UI cut — which the
+  mechanical `prd-card-writer` does not hold), and it is PERSISTED onto the epic card. The card-writer
+  emits these keys ONLY when handed them; otherwise it **omits** them.
+- **Contiguity invariant:** waves partition the groups in `level` order — a wave is a contiguous run
+  of groups. `wave` numbers ascend 1,2,3…; every group in the same wave shares one `wave_name`.
+- **Single-run:** ≤1 distinct `wave_name` across all groups (e.g. a light-lane 1-child epic) means
+  "launch in one run" — the orchestrator leaves the wave keys ABSENT rather than tagging everything
+  `wave: 1`.
+
+**Launch waves (render-time — NOT persisted):** the human-facing launch plan is derived, never
+stored beyond the three keys above:
+- The **wave view** = group the epic's `groups[]` by `wave_name`, ordered by `wave`; each wave's
+  cards = the union of its groups' `.cards`. Consumers: `/prd` final message ("Piano di
+  implementazione suggerito") and `/new`/`/new2` final message ("prossime wave rimanenti", joining
+  wave membership with each card's on-disk `status`).
+- The **engine recommendation** (`/new` vs `/new2`) is computed at render time and is **runtime-aware**
+  — `/new2` needs the Workflow tool and is **Claude-only** (see `framework/agents/runtime-portability-protocol.md`
+  § "Workflow acceleration" — *no Codex equivalent*). It is **never persisted** on the card: a durable,
+  cross-tool artifact must not carry a runtime-capability recommendation a Codex consumer cannot execute.
+- The anti-parallel hard rule ("no other work on the same files between waves") and any project-specific
+  post-wave gates (surfaced from `.baldart/overlays/prd.md`) are render-time constants, likewise not persisted.
+
 ## Acceptance-criteria grammar (EARS) + per-AC oracles (since the EARS+verify wave)
 
 **Why**: a prose AC passes gates without being verifiable ("handle it correctly"), and

package/package.json

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

package/src/commands/configure.js

@@ -1508,10 +1508,17 @@ async function configure(opts = {}) {
     const enabledTools = (merged.tools && Array.isArray(merged.tools.enabled) && merged.tools.enabled.length)
       ? merged.tools.enabled : ['claude'];
     if (fs.existsSync(path.join(cwd, '.framework'))) {
-      new SymlinkUtils(cwd).mergeAgents({ tools: enabledTools });
+      const symlinks = new SymlinkUtils(cwd);
+      symlinks.mergeAgents({ tools: enabledTools });
+      // Also re-merge SKILLS: the feature-gate (src/utils/skill-gate.js) depends
+      // on the `features.*` just written. On first install `mergeSkills` ran
+      // fail-open BEFORE this config existed (linking everything), so this pass
+      // is what actually prunes the gated-off skills. Without it, gating never
+      // takes effect until the next `baldart update`.
+      symlinks.mergeSkills({ tools: enabledTools });
     }
   } catch (err) {
-    UI.warning(`Agent re-merge after configure failed (${err.message}) — run \`npx baldart doctor\` to heal.`);
+    UI.warning(`Agent/skill re-merge after configure failed (${err.message}) — run \`npx baldart doctor\` to heal.`);
   }
 
   // v5.1.0 — research library: create + seed ${paths.research_dir} right after

package/src/commands/doctor.js

@@ -409,6 +409,47 @@ async function detectState(cwd, opts = {}) {
       }
     } catch (_) { /* never block doctor on probe */ }
 
+    // ---- Feature-gated skill drift (skill-gate) ------------------------
+    // A skill whose `requires_feature` frontmatter is no longer satisfied
+    // (feature flipped off in baldart.config.yml) may still be linked from a
+    // prior install. `configure` and `update` both re-merge (which prunes), but
+    // a user who edits the config and runs ONLY `doctor` should be told. The
+    // reverse (a feature just turned ON, gated skill not yet linked) is covered
+    // by the missing-skills path. Advisory only (fix = `reconcile-skills`, a
+    // plain re-merge); never blocks. Fully fail-safe.
+    state.gatedSkillsLinked = [];
+    try {
+      if (state.frameworkPresent) {
+        const { resolveSkillGate } = require('../utils/skill-gate');
+        const { getAdapter } = require('../utils/tool-adapters');
+        const frameworkSkillsDir = path.join(cwd, '.framework', 'framework', '.claude', 'skills');
+        const gate = resolveSkillGate(frameworkSkillsDir, cwd);
+        if (!gate.failOpen && gate.gatedOff.length) {
+          const toolsEnabled = (config && !config.__malformed && config.tools && Array.isArray(config.tools.enabled))
+            ? config.tools.enabled : ['claude'];
+          const seen = new Set();
+          for (const toolName of toolsEnabled) {
+            let adapter;
+            try { adapter = getAdapter(toolName, cwd); } catch (_) { continue; }
+            const skillsRel = adapter.skillsDir();
+            for (const name of gate.gatedOff) {
+              if (seen.has(name)) continue;
+              const linkPath = path.join(cwd, skillsRel, name);
+              try {
+                const lst = fs.lstatSync(linkPath);
+                if (!lst.isSymbolicLink()) continue;
+                const resolved = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
+                if (resolved === path.join(frameworkSkillsDir, name)) {
+                  seen.add(name);
+                  state.gatedSkillsLinked.push(name);
+                }
+              } catch (_) { /* absent */ }
+            }
+          }
+        }
+      }
+    } catch (_) { /* never block doctor on probe */ }
+
     // ---- Workflow symlink integrity (since v4.14.0) --------------------
     // Dynamic workflows (.js) are Claude-only and per-item symlinked into
     // `.claude/workflows/`. Unlike agents there is NO hard discovery gate —
@@ -1086,6 +1127,30 @@ function planActions(state) {
     });
   }
 
+  // Feature-gated skill drift (skill-gate). Advisory — these skills' gating
+  // feature is now off, but they're still linked from a prior install; they'd
+  // only refuse at runtime and waste the Codex skill-description budget. A plain
+  // re-merge prunes them (same rationale as the agent/workflow repairs).
+  if (state.gatedSkillsLinked && state.gatedSkillsLinked.length > 0) {
+    actions.push({
+      key: 'reconcile-skills',
+      label: `Unlink ${state.gatedSkillsLinked.length} feature-gated skill(s)`,
+      why: `These skills are still linked but their gating feature is now off in baldart.config.yml: ${state.gatedSkillsLinked.join(', ')}. They refuse at runtime and consume Codex's ~2% skill-description budget. Re-merging prunes them (re-enable the feature to bring them back).`,
+      autoOk: true,
+      run: async () => {
+        const SymlinkUtils = require('../utils/symlinks');
+        const cfg = loadConfig(process.cwd());
+        const enabledTools = (cfg && !cfg.__malformed
+          && cfg.tools && Array.isArray(cfg.tools.enabled))
+          ? cfg.tools.enabled
+          : ['claude'];
+        const symlinks = new SymlinkUtils();
+        symlinks.mergeSkills({ tools: enabledTools });
+        UI.success(`Reconciled feature-gated skills for tools: ${enabledTools.join(', ')}`);
+      },
+    });
+  }
+
   // Root primitives integrity (since v4.83.0). Regenerates AGENTS.md / CLAUDE.md
   // from the versioned skeleton + config + overlay when missing, still a legacy
   // symlink, or drifted. Offline + idempotent. A handwritten file is NOT touched

package/src/utils/skill-gate.js

@@ -0,0 +1,139 @@
+/**
+ * skill-gate.js — install-time feature-gating for framework skills.
+ *
+ * BALDART ships ~40 skills; Codex reserves only ~2% of its context window for
+ * skill descriptions, so linking every skill (including ones whose gating
+ * `features.*` flag is OFF, which then refuse at runtime anyway) wastes that
+ * budget. This module decides, per install/update, WHICH framework skills to
+ * link into a consumer, based on an OPTIONAL `requires_feature` frontmatter
+ * field in each skill's `SKILL.md`.
+ *
+ * The gate is PURELY install-time (resolved here by the Node installer) — both
+ * Claude (`.claude/skills/`) and Codex (`.agents/skills/`) simply see fewer
+ * directories. Neither runtime interprets `requires_feature`; it is a BALDART
+ * authoring construct, ignored by the skill loaders exactly like `version:` /
+ * `effort:`. So the filter is natively portable across both tools and applied
+ * from a single code path (the gate is shared SEMANTICS, not runtime mechanics).
+ *
+ * Frontmatter contract (all OPTIONAL — a skill with no `requires_feature` is
+ * ALWAYS linked, backwards-compatible default):
+ *   requires_feature: has_design_system                 # string  → link iff true
+ *   requires_feature: [has_design_system, has_e2e_review] # list = AND (all true)
+ *
+ * Fail-open everywhere (never hide a skill by accident — the safety net must
+ * not become a tribunal):
+ *   - config absent / unreadable / malformed → link EVERYTHING.
+ *   - a single skill's frontmatter malformed  → link THAT skill (per-skill),
+ *     never crash the whole merge.
+ *
+ * NOTE: we read `features.*` DIRECTLY from baldart.config.yml rather than reuse
+ * `agent-slots.resolveAgentFlags()` — that flag set intentionally covers only
+ * the keys the agent SLOT sources reference and omits `has_prd_workflow` /
+ * `has_e2e_review`, which ARE skill gates. Reading the raw block keeps the gate
+ * correct for every existing (and future) `features.*` key with no coupling.
+ *
+ * This introduces NO new `baldart.config.yml` key (it consumes existing
+ * `features.*`) — the schema-change propagation rule does NOT apply. It is
+ * skill-frontmatter metadata, like `version`/`effort`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Load the `features` block from baldart.config.yml.
+ * @returns {{ features: Object|null }} `features: null` signals "config
+ *   unavailable" → callers must fail-open (link everything).
+ */
+function loadFeatures(cwd) {
+  try {
+    const yaml = require('js-yaml');
+    const cfgPath = path.join(cwd, 'baldart.config.yml');
+    if (!fs.existsSync(cfgPath)) return { features: null };
+    const cfg = yaml.load(fs.readFileSync(cfgPath, 'utf8'));
+    if (!cfg || typeof cfg !== 'object') return { features: null };
+    const features = (cfg.features && typeof cfg.features === 'object') ? cfg.features : {};
+    return { features };
+  } catch (_) {
+    return { features: null };
+  }
+}
+
+/**
+ * Extract the OPTIONAL `requires_feature` from a skill's SKILL.md frontmatter.
+ * @returns {string[]|null} normalized list of required feature keys, or null
+ *   when the skill is ungated / has no SKILL.md / frontmatter is unparseable
+ *   (fail-open: null ⇒ always link).
+ */
+function readRequiredFeatures(skillDir) {
+  try {
+    const skillMd = path.join(skillDir, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) return null;
+    const raw = fs.readFileSync(skillMd, 'utf8');
+    if (!raw.startsWith('---')) return null;
+    // Frontmatter is between the first two `---` fences.
+    const end = raw.indexOf('\n---', 3);
+    if (end === -1) return null;
+    const fmText = raw.slice(3, end);
+    const yaml = require('js-yaml');
+    const fm = yaml.load(fmText);
+    if (!fm || typeof fm !== 'object') return null;
+    const req = fm.requires_feature;
+    if (req == null) return null;
+    const list = (Array.isArray(req) ? req : [req])
+      .map(x => String(x).trim())
+      .filter(Boolean);
+    return list.length ? list : null;
+  } catch (_) {
+    // Malformed frontmatter for THIS skill → fail-open (link it).
+    return null;
+  }
+}
+
+/**
+ * Decide which framework skills to link vs skip for this consumer.
+ *
+ * @param {string} frameworkSkillsDir absolute path to
+ *   `.framework/framework/.claude/skills/`
+ * @param {string} cwd consumer repo root (where baldart.config.yml lives)
+ * @returns {{ toLink: string[], gatedOff: string[], failOpen: boolean }}
+ *   `toLink` = skill dir names to link; `gatedOff` = skill dir names to skip
+ *   (and prune if already linked); `failOpen` = true when config was
+ *   unavailable so nothing was gated.
+ */
+function resolveSkillGate(frameworkSkillsDir, cwd) {
+  const result = { toLink: [], gatedOff: [], failOpen: false };
+
+  let names = [];
+  try {
+    names = fs.readdirSync(frameworkSkillsDir).filter(name => {
+      if (name.startsWith('.')) return false;
+      try { return fs.lstatSync(path.join(frameworkSkillsDir, name)).isDirectory(); }
+      catch (_) { return false; }
+    });
+  } catch (_) {
+    return result; // no framework skills dir → empty sets, caller handles
+  }
+
+  const { features } = loadFeatures(cwd);
+
+  // Config unavailable → fail-open: link everything, gate nothing.
+  if (features === null) {
+    result.failOpen = true;
+    result.toLink = names.slice();
+    return result;
+  }
+
+  for (const name of names) {
+    const required = readRequiredFeatures(path.join(frameworkSkillsDir, name));
+    if (!required) { result.toLink.push(name); continue; }
+    // AND semantics: link iff EVERY required feature is explicitly true.
+    const allOn = required.every(f => features[f] === true);
+    if (allOn) result.toLink.push(name);
+    else result.gatedOff.push(name);
+  }
+
+  return result;
+}
+
+module.exports = { resolveSkillGate, readRequiredFeatures, loadFeatures };