baldart 5.6.0 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.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.7.0

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,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 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.3.1
+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/new2/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 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.8.1
+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,10 @@
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · [SemVer](https://semver.org/).
 
+## 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.6.1
+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-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

@@ -634,7 +634,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baldart",
-  "version": "5.6.0",
+  "version": "5.7.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 };

package/src/utils/symlinks.js

@@ -210,7 +210,7 @@ class SymlinkUtils {
    */
   mergeSkills(opts = {}) {
     const tools = (opts.tools && opts.tools.length) ? opts.tools : ['claude'];
-    const aggregate = { linked: [], skipped: [], conflicts: [] };
+    const aggregate = { linked: [], skipped: [], conflicts: [], pruned: [], gatedOff: [] };
 
     const frameworkSkillsDir = path.join(this.cwd, FRAMEWORK_PAYLOAD, '.claude', 'skills');
     if (!fs.existsSync(frameworkSkillsDir)) {
@@ -218,17 +218,31 @@ class SymlinkUtils {
       return aggregate;
     }
 
-    const frameworkSkills = fs.readdirSync(frameworkSkillsDir).filter(name => {
-      if (name.startsWith('.')) return false;
-      const full = path.join(frameworkSkillsDir, name);
-      return fs.lstatSync(full).isDirectory();
-    });
+    // Feature-gate: link only the skills whose `requires_feature` frontmatter is
+    // satisfied by this consumer's `features.*` (fail-open when config is
+    // unavailable → link everything). Resolved ONCE and applied to EVERY tool
+    // from this single code path — the gate is shared semantics, so Claude and
+    // Codex stay identical by construction. See src/utils/skill-gate.js.
+    const gate = require('./skill-gate').resolveSkillGate(frameworkSkillsDir, this.cwd);
+    const frameworkSkills = gate.toLink;
+    aggregate.gatedOff = gate.gatedOff.slice();
+    if (gate.gatedOff.length) {
+      UI.info(`Feature-gate: ${gate.gatedOff.length} skill(s) skipped (gating feature off): ${gate.gatedOff.join(', ')}`);
+    }
 
     for (const tool of tools) {
       const result = this._mergeSkillsForTool(tool, frameworkSkills, frameworkSkillsDir);
       aggregate.linked.push(...result.linked);
       aggregate.skipped.push(...result.skipped);
       aggregate.conflicts.push(...result.conflicts);
+
+      // Prune direction: remove any pre-existing framework symlink for a skill
+      // that is now gated-off (e.g. a feature flipped false after a prior
+      // install, or a fail-open install that linked everything before config
+      // existed). Only OUR framework symlinks are removed — never a real user
+      // skill dir, never a user-override symlink pointing elsewhere.
+      const pruneResult = this._pruneGatedSkillsForTool(tool, gate.gatedOff, frameworkSkillsDir);
+      aggregate.pruned.push(...pruneResult.pruned);
     }
 
     if (aggregate.conflicts.length > 0) {
@@ -329,6 +343,54 @@ class SymlinkUtils {
     return result;
   }
 
+  /**
+   * Prune framework skill symlinks that are now gated-off — internal.
+   *
+   * This is the reconcile (removal) direction of the feature-gate: turning a
+   * `features.*` flag off (or a fail-open first install that linked everything
+   * before config existed) must actually REMOVE the stale symlinks, or the
+   * skill-description budget never shrinks. Each `name` in `gatedOff` is a
+   * framework skill name by construction (it came from the framework catalog),
+   * so basename∈catalog is guaranteed; we still verify the link RESOLVES to our
+   * framework source for that exact skill before unlinking. Safety invariants:
+   *   - never touch a real directory (a user-authored skill of the same name);
+   *   - never touch a symlink pointing ANYWHERE ELSE (a user override, cf. the
+   *     `user-symlink-override` branch in _mergeSkillsForTool).
+   */
+  _pruneGatedSkillsForTool(toolName, gatedOff, frameworkSkillsDir) {
+    const { getAdapter } = require('./tool-adapters');
+    const adapter = getAdapter(toolName, this.cwd);
+    const result = { pruned: [] };
+    if (!gatedOff || !gatedOff.length) return result;
+
+    const skillsRel = adapter.skillsDir();
+    const userSkillsDir = path.join(this.cwd, skillsRel);
+    if (!fs.existsSync(userSkillsDir)) return result;
+
+    for (const name of gatedOff) {
+      const linkPath = path.join(userSkillsDir, name);
+      let lstat = null;
+      try { lstat = fs.lstatSync(linkPath); } catch (_) { continue; /* absent */ }
+
+      // Only ever remove a symlink — a real dir here is a user-authored skill.
+      if (!lstat.isSymbolicLink()) continue;
+
+      const current = fs.readlinkSync(linkPath);
+      const resolved = path.resolve(path.dirname(linkPath), current);
+      const frameworkTarget = path.join(frameworkSkillsDir, name);
+
+      // Unlink ONLY when it resolves to OUR framework source for this skill.
+      // A symlink pointing elsewhere is a deliberate user override → leave it.
+      if (resolved === frameworkTarget) {
+        fs.unlinkSync(linkPath);
+        UI.info(`[${adapter.label}] Skill unlinked (feature gated off): ${path.join(skillsRel, name)}`);
+        result.pruned.push({ tool: toolName, name });
+      }
+    }
+
+    return result;
+  }
+
   // -----------------------------------------------------------------------
   // Public composite operations
   // -----------------------------------------------------------------------
@@ -827,7 +889,10 @@ class SymlinkUtils {
           UI.warning(`[${adapter.label}] Legacy bulk skills symlink at ${skillsRel}. Run \`npx baldart update\` to convert to per-item.`);
           allValid = false;
         } else {
-          const sample = ['skill-creator', 'frontend-design', 'bug', 'prd', 'capture'];
+          // Sample ONLY always-linked skills — never feature-gated ones (e.g.
+          // prd/capture), which are legitimately absent when their feature is
+          // off and would make this probe brittle / falsely alarming.
+          const sample = ['skill-creator', 'bug', 'simplify', 'overlay', 'find-skills'];
           let frameworkLinks = 0;
           sample.forEach(name => {
             const p = path.join(skillsDir, name);