baldart 5.5.0 → 5.7.0

package/CHANGELOG.md

@@ -5,6 +5,125 @@ 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
+batch chiuse 6/6 card + epic come "✅ DONE, merged" mentre il goal dell'epic era invisibile
+sul ~90% delle schermate: il root cause era in `/prd` (inventario ISA sui consumer del
+meccanismo invece che sui proprietari della superficie; recipe ancorata su un componente
+`@deprecated`; due gate phantom-stampati), attraversava card che nessun gate poteva salvare
+(coverage passata vacuamente su un inventario sbagliato), e veniva sigillato da `/new`/`new2`
+(chiusura epic al commit dell'ultima card — PRIMA della final review — con predicato
+conta-figli, nessun verdetto PARTIAL, safety-commit che spazzava file non gated su develop,
+commit agent in detour sul main checkout). 28 finding crit/high confermati adversarialmente;
+ogni fix è ancorato a un'evidenza del run.
+
+- **Chiusura epic v2 (`/new` 2.3.0 + `new2` 1.8.0)**: SOLO in merge phase (il gate
+  commit-time v4.99.0 è ritirato — aveva anche un anchor bug `^parent:` che lo rendeva
+  no-op); predicato esteso (figli **e follow-up** DONE + nessun residual bloccante +
+  **AC epic verificati con oracoli**); blocklist JS + guardia post-merge (F-029 twin) +
+  ramo **REOPEN** (il ratchet è bidirezionale); classe finding **closure-invalidating**
+  (un "goal not achieved" è un difetto di STATO — il fix di prosa non chiude).
+- **Verdetto PARTIAL calcolato** (`final-review.md` + `buildReport`): residual HIGH+ /
+  epic aperta / AC epic `[ ]` ⇒ headline `⚠️ PARTIAL` col gap nominato; sezione
+  `## Epic goal`; severity sui residui; "nulla perso" mai come surrogato di "non finito".
+- **Igiene git orchestrata**: `merge-worktree.sh --safety-sweep allowlist:` (worktree-manager
+  1.2.0 — il codice non gated va in quarantena etichettata, mai nel trunk sotto un
+  "[safety]" opaco); isolamento worktree del commit agent esteso ai TOOL con evidenza
+  porcelain + guardia JS (era 7.1M di detour + stash dangling); divieto stash + audit
+  post-run dei commit non-card e degli stash del batch (mai "non miei da droppare").
+- **Review**: relay Codex della final review in foreground `--wait` (il polling veniva
+  ucciso dall'enforcement structured-output a 83s/600s → fallback freddo da 3.68M);
+  esito **refuted** ratificato in `new2-resolve` (premessa falsa = zero edit) + divieto
+  di fix che disattivano verifiche mandate da AC (`verification-posture-change`);
+  suite aggiunte dalla card ESEGUITE targeted pre-commit (`completeness.md` 1b).
+- **Routing**: `hasMockup` semantico (la card COSTRUISCE la UI mockata — un bare
+  `links.design` su card docs va all'owner router; era 6.55M di ui-expert su una card
+  docs+ADR).
+- **`/prd` 1.6.0 (il root cause)**: categoria ISA **UI ROLE FAMILY (registry-first)**
+  (owner della superficie dal registry + flag BLOCK su `@deprecated`); §0 LOAD CONTRACT
+  su `discovery-phase.md` (vista PARTIAL ⇒ offset-Read fino in fondo — la coda persa
+  conteneva il Codex completeness cross-check mai eseguito); `module_read` stamps
+  ESEGUITI + item 0-ii Phase-evidence audit (2 gate phantom-stampati sul run reale);
+  `step_3_mode` enum chiuso + contratto `skipped` (mai design hand-authored fuori
+  `/ui-design`) + Reconciliation-lite senza mockup + trigger di ri-enumerazione ISA;
+  gate quantificatore-universale sugli AC epic (`invariant_owners:`); stamp holistic
+  **evidence-gated** (`stamp-holistic-audit.js --audit-report` → `agents_run`; senza
+  artefatto → `status: skipped` = ASSENTE per `/new`); card-writer 1.2.0
+  (self-validation eseguita, epic `ac_verification` obbligatoria, mai count hardcodato,
+  `links.design` solo su card UI, invariante baseline snapshot); HARD RULE mw-docs
+  (+ guardia `/mw` su `kind: docs`); EDIT CONTRACT dello state file (5 retry ciechi
+  da ~250k); `research-protocol.md` pre-flight libreria in difesa.
+- **Tooling maintainer**: `new-session-audit.mjs` guadagna **EPIC_AC_UNMET** (FAIL —
+  retro-validato: il run FEAT-0068 ora fallisce l'audit invece di passarlo) e
+  **GATE_DISABLED_BY_FIX** (WARN) + fix del digest-writer su id workflow con `/`;
+  `check-new-parity.mjs` esteso a 21 policy (chiusura epic, PARTIAL, mockup semantico —
+  con token FORBIDDEN sui meccanismi ritirati).
+- Deliberatamente rinviati (MED/LOW non verificati dal pass avversariale): digest
+  per-batch dei moduli di riferimento (tassa cache ~3-5M), card shape
+  VERIFY-ONLY/MECHANICAL-MIGRATION, sampling visivo del goal epic in final review,
+  script `update-state.mjs` per `/prd` (mitigato dall'EDIT CONTRACT).
+- Codex parity: **portable** — le policy vivono nei moduli prose SSOT (`/new`, `/prd`)
+  e in script zero-dep/shell; i workflow Claude-only (`new2*`, `new-final-review`)
+  hanno ricevuto le STESSE policy dei twin prose (guardia di parity estesa a 21 regole).
+  Nessuna nuova chiave `baldart.config.yml` → la schema-change propagation rule non si
+  applica.
+
 ## [5.5.0] - 2026-07-03
 
 **Migration deploy chain hardened (FEAT-0067 post-mortem — mayo).** The batch's DB

package/VERSION

@@ -1 +1 @@
-5.5.0
+5.7.0

package/framework/.claude/agents/CHANGELOG.md

@@ -7,6 +7,22 @@ per-item agent merge, the doctor probes, and the discovery hooks — like
 
 Formato: [Keep a Changelog](https://keepachangelog.com/) · per-agent SemVer.
 
+## [prd-card-writer v1.2.0] — 2026-07-04 (framework v5.6.0 — FEAT-0068 post-mortem)
+
+- **Epic AC rules**: mai count di figli hardcodato ("le 6 sub-card"); AC con
+  quantificatore universale su una superficie ⇒ `invariant_owners:` dal census
+  registry/ISA; `ac_verification` OBBLIGATORIA sull'epic (≥1 oracolo per goal AC —
+  consumata dal gate di chiusura epic).
+- **`links.design` FORBIDDEN su card che non costruiscono UI mockata** (docs/test/
+  meta-only ⇒ owner coder, riferimenti di contesto in `canonical_docs.additional_refs`)
+  — un pointer vagante clampava la build a ui-expert (6.55M su una card docs).
+- **Invariante snapshot-suite**: una card che CREA una suite visual-regression dichiara
+  il lifecycle delle baseline (generate+committate in-card, o assertion-based) — pena
+  BLOCKER di authoring.
+- **Self-validation**: il writer ESEGUE `validate-card-baseline.js --prd` sul proprio
+  output e ritorna solo su exit 0 (token EARS sempre inglesi verbatim) — mai asserire
+  "YAML-valid" senza aver eseguito il validator.
+
 ## [prd-card-writer v1.1.0] — 2026-07-03 (framework v5.4.0)
 
 - **Proportionality lower-bound** in Card Atomicity Rules: a Tier-Gate TRIVIAL/LIGHT

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

@@ -1,6 +1,6 @@
 ---
 name: prd-card-writer
-version: 1.1.0
+version: 1.2.0
 description: "Generates atomic backlog cards from an approved PRD. Handles card YAML writing, dependency graph computation, parallel group assignment, and traceability matrices (FR/NFR, ISA, UI). Invoked by the /prd skill at Step 5 to offload the heaviest mechanical phase from the main context. Also runs in Standalone Single-Card Mode to author ONE baseline-conformant follow-up/CHORE/BUG/issue card (no epic+children) — invoked by /new (AC-deferral), new2/new2-resolve, and /issue-review. The canonical card writer: every card-creation path delegates here rather than hand-writing a partial stub."
 model: opus
 effort: high
@@ -335,7 +335,18 @@ applies even when N=1.
   - `business_rationale` (extended — full strategic context)
   - `scope.summary` + `scope_boundaries` (in_scope summary + out_of_scope deferrals)
   - `acceptance_criteria` as `[ ] [AC-EPIC-N]` items rolling up the PRD ACs (NOT
-    duplicating child ACs — track end-to-end outcomes only)
+    duplicating child ACs — track end-to-end outcomes only). **v5.6.0 (FEAT-0068)
+    epic-AC rules:** (1) NEVER hardcode a child count ("all 6 sub-cards DONE" broke the
+    moment follow-ups appeared — write "all child cards **including any added later**");
+    (2) an AC with a universal quantifier over a surface ("every screen", "tutte le
+    route") MUST list its surface owners in `invariant_owners:` (from the ISA UI ROLE
+    FAMILY census) so the closure gate can re-verify them.
+  - `ac_verification` — **REQUIRED on the epic (v5.6.0)**: ≥1 executable oracle per
+    top-level goal AC (same grounding rule as child cards — only verified commands/greps;
+    else `manual:`). The `/new`/`new2` epic-closure gate RUNS these before flipping the
+    epic DONE — an epic with no oracle can only close via manual evidence, which is
+    slower. (FEAT-0068's goal was greppable at authoring time: "every top-edge family
+    member consumes `--safe-area-inset-top`".)
   - `definition_of_done`: epic-level (e.g. "all sub-card DONE", "PRD test scenarios
     executed", "ssot-registry entry added")
   - `execution_strategy` block with `recommended_mode`, `groups[]` (each with
@@ -505,6 +516,14 @@ Every card MUST include ALL fields from the template:
   `manual: <what a human checks>`. Genuinely undecidable → `[NEEDS CLARIFICATION: …]`.
   Non-manual oracles SHOULD also appear in `validation_commands` (the validator warns on
   drift). Consumed by `/new` Phase 2.5, which EXECUTES them.
+- **Snapshot-suite lifecycle invariant (v5.6.0 — FEAT-0068):** a card whose scope CREATES a
+  visual-regression / snapshot / screenshot-diff suite MUST declare the baseline lifecycle in
+  its requirements + DoD: EITHER "baselines generated (`--update-snapshots` or equivalent) and
+  committed IN THIS CARD" (the generate command listed in `validation_commands`/MAY-EDIT
+  covering the baseline dir) OR "assertion-based checks with screenshots advisory-only". A
+  suite whose baselines "arrive later" with no declared bootstrap is a card-authoring BLOCKER
+  — on the real run it detonated as a merge-blocker and the 4.73M repair "fixed" it by
+  flag-gating the epic's only visual verification.
 - `definition_of_done` (checklist including doc invariants). **When `features.has_i18n: true`** AND the
   card introduces user-facing strings, the DoD MUST carry an i18n-completeness line — NOT merely "strings
   via `t()` + registered", but: *"new keys authored in the source locale + the i18n context registry (by
@@ -519,7 +538,12 @@ Every card MUST include ALL fields from the template:
 - `review_profile` (`skip`|`light`|`balanced`|`deep` — computed via Rule C, or honored if pre-set)
 - `files_likely_touched` (exact paths with NEW/MODIFY)
 - `links.prd` (path to PRD)
-- `links.design` (REQUIRED for any card with UI scope) — the card's screen design
+- `links.design` (REQUIRED for any card with UI scope; **FORBIDDEN on cards that build no
+  mocked UI — v5.6.0**: a docs/test/meta-only card, or one whose `files_likely_touched` has
+  no component/style path, must NOT carry `links.design` even "for context" — downstream the
+  `/new` mockup-first router treats it as a build target and clamps the card to `ui-expert`;
+  on FEAT-0068 the epic explainer stamped on a docs+ADR card cost 6.55M. Point context-only
+  references in `canonical_docs.additional_refs` instead) — the card's screen design
   reference, resolved to a path **that exists on disk in the worktree**:
   - **design.html when one was generated** for this screen (Step 3 produced it).
   - **ELSE the screen's canonical mockup PNG** under `${paths.prd_dir}/<slug>/mockups/`
@@ -732,6 +756,16 @@ The consumer (`new/SKILL.md`) reads `execution_strategy.groups[].level` and
 
 ## Output Format
 
+**Self-validation BEFORE returning (v5.6.0 — you own your domain's deterministic hygiene).**
+Run `node .framework/framework/scripts/validate-card-baseline.js --prd <your card files>` (or
+the `VALIDATOR` path the caller passed) on your own output and fix every deterministic failure
+(enum values, EARS keyword language — the tokens are ALWAYS English verbatim, only the clause
+body follows `identity.language` —, forbidden patterns, missing required fields) IN THIS
+CONTEXT before returning. Return only on exit 0, and state `validator: exit 0 (N cards)` in
+the summary. NEVER assert "YAML-valid / pattern-clean" without having executed the validator —
+on a real session that unexecuted claim cost a full orchestrator round-trip when Step 6
+bounced all 6 children on Italian EARS tokens. Step 6 still re-runs it as the independent gate.
+
 Return to the caller a structured summary:
 
 1. **Card list** — IDs and titles of all cards created

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,33 @@
 
 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
+  (timing: chiudeva PRIMA che la final review potesse smentire il goal; anchor bug:
+  `^parent:` non matchava il `parent:` annidato sotto `group:` → gate no-op).
+  `merge-cleanup.md` 5e ora richiede: figli **e follow-up** DONE + nessun residual
+  bloccante/finding closure-invalidating + **AC epic verificati con evidenza**
+  (oracoli `ac_verification`); ramo **REOPEN** per un'epic DONE con scope aperto.
+- **Classe finding "closure-invalidating"** (`final-review.md` F.4): un finding
+  "goal/AC epic non raggiunto" è un difetto di STATO — il fix testuale non basta,
+  l'epic non chiude (o riapre) nello stesso repair commit.
+- **Verdetto PARTIAL calcolato** (`final-review.md` § Report verdict): residual HIGH+ /
+  epic aperta / AC epic `[ ]` ⇒ prima riga `⚠️ PARTIAL` col gap nominato; ✅ riservato.
+- **Routing mockup semantico** (`implement.md` 6a): `HAS_MOCKUP` = la card COSTRUISCE
+  la UI mockata (design_src, o design + bindings/file UI) — un bare `links.design` su
+  card docs/meta va all'owner router (era: clamp a ui-expert, 6.55M su una card docs).
+- **Stamp holistic evidence-gated** (`implement.md` step 4 P1): uno stamp senza
+  `agents_run` non vuoto = ASSENTE → il plan-auditor gira (phantom stamp FEAT-0068).
+- **Suite aggiunte dalla card: eseguite, non solo parse** (`completeness.md` 1b): uno
+  spec ADDED va RUN targeted pre-commit; suite snapshot senza lifecycle baseline
+  dichiarato = `Partial` → gap-fix subito (era: merge-blocker + repair da 4.73M che
+  flag-gatava la verifica dell'epic).
+
 ## 2.2.1 — 2026-07-03 (FEAT-0067 post-mortem: migration vocabulary aliases)
 
 - Il gate di delega `-auto` (condizione 4) e il Migration Gate Phase 0 1b (setup.md

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

@@ -1,7 +1,8 @@
 ---
 name: new
 effort: medium
-version: 2.2.1
+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/new/references/commit.md

@@ -33,14 +33,18 @@
     a. Edit the backlog YAML (`${paths.backlog_dir}/<CARD-ID>.yml`): set `status: DONE`, add `completed_date: <today>`, and add `provenance.implementation_session: <SESSION-ID>` (this run's session UUID — get it with `Bash(echo "${CLAUDE_CODE_SESSION_ID:-}")`; if empty, omit the field). Merge into any existing `provenance:` block written by `/prd` — do NOT overwrite `planning_session`. This makes an implementation bug traceable back to the session that produced it (`~/.claude/projects/*/<id>.jsonl`).
     b. Add implementation notes summarizing what was built.
     c. **Update `${paths.references_dir}/ssot-registry.md`** — add/update the entry for this card's feature area. The pre-commit doc-freshness hook BLOCKS commits that touch `${paths.backlog_dir}/` without a corresponding ssot-registry update. Always include ssot-registry.md in the same commit as the backlog YAML.
-    c-bis. **Epic-closure gate (deterministic — since v4.99.0)**: if the card YAML declares a parent epic (`parent:` field), check — AFTER step a set this card DONE — whether it was the LAST open child. Deterministic count, no judgement:
-       ```bash
-       PARENT=$(awk '/^parent:/ {print $2; exit}' ${paths.backlog_dir}/<CARD-ID>.yml)
-       if [ -n "$PARENT" ]; then
-         PENDING=$(grep -l "^parent: ${PARENT}" ${paths.backlog_dir}/*.yml | xargs grep -L "^status: DONE" | wc -l)
-       fi
-       ```
-       When `PENDING` is `0`: flip the PARENT epic's status in its ssot-registry.md entry to DONE **in the SAME commit**, and if the parent epic has its own backlog YAML, set its `status: DONE` + `completed_date` too. Non-triggers (do nothing, idempotent): the card has no `parent:`; siblings still pending (`PENDING > 0`); the parent entry is already DONE. This closes a recurring consumer gap: step 28c alone updates the CARD's feature-area entry, so epics stayed `IN_PROGRESS` after their last child closed and were only caught by the nightly doc routine (3 confirmed occurrences across two audit windows).
+    c-bis. **Epic closure does NOT happen here (v5.6.0 — the v4.99.0 commit-time gate is RETIRED).**
+       Two proven defects (FEAT-0068 post-mortem): (1) **timing** — closing at the last card's
+       commit runs structurally BEFORE the final review can disprove the epic goal (the FEAT-0068
+       epic closed DONE 13 minutes before the review proved the goal unmet on ~90% of screens),
+       and the commit context cannot see follow-up cards materialized later in the batch;
+       (2) **anchor bug** — the retired gate grepped `^parent:` but the card schema nests
+       `parent:` indented under `group:`, so it was a silent no-op on schema-conformant cards.
+       Epic closure now lives ONLY in the merge phase (`merge-cleanup.md` Phase 6b step 5e,
+       extended predicate: children **and follow-ups** DONE + no blocking residual + **epic ACs
+       verified**), which runs AFTER the final review. At commit time the parent epic and every
+       sibling card YAML are READ-ONLY. The epic-staleness safety net the v4.99.0 gate closed
+       stays closed by Phase 6b 5e + the nightly doc routine.
     d. **Verify the write**: re-read the YAML file and confirm `status: DONE` is present. If not, retry the edit.
     e. Stage BOTH the updated YAML AND ssot-registry.md, then commit (or as an immediate follow-up commit if the Phase 4 implementation commit already happened). When this produces a SECOND commit for the card, record BOTH hashes in the tracker (`commit: <impl-hash> + <done-hash>`) so traceability/bisect is unambiguous.
 29. **Update tracker**: move card to `## Completed Cards` with commit hash(es), summary, flags, **and `card_status: DONE (verified)`** — the tracker is the only state surface (§ "State surface — the tracker only"); do not also emit a TaskUpdate or Progress-Bar turn for the transition. If you surface the card completion to the user at all, do it as a short prose line folded into the commit turn, never a dedicated turn.

package/framework/.claude/skills/new/references/completeness.md

@@ -36,6 +36,16 @@ Before triggering any review, you MUST verify that the coder agent implemented *
    `conditional_items` section → flag as `Missing` (the coder must document the branch taken).
 
 1. **Enter Phase 2.5 (completeness)** — **no standalone tracker write** for phase entry (§ "Context Tracking" allowlist; the tracker records only `2.5-completeness DONE` at step 6, co-emitted). Proceed directly to the next step.
+1b. **Card-added test suites must RUN, not just parse (v5.6.0 — FEAT-0068).** If the card's diff
+   ADDS or modifies a test/spec file, the completeness evidence for that item is a targeted
+   EXECUTION of exactly that file (`npx vitest run <file>` / `npx playwright test <file>` / the
+   toolchain equivalent), in the worktree, before commit — a `--list`/parse check only proves the
+   file compiles, not that the suite can pass. A suite that cannot run yet by design (e.g. a
+   visual-regression suite whose baselines are generated later) is only `Done` if the card
+   EXPLICITLY declares that lifecycle (see `card-schema.md` § snapshot-suite invariant) AND the
+   declared bootstrap command is exercised; otherwise classify `Partial` and route to the
+   gap-fix loop NOW — the FEAT-0068 card shipped a baseline-less suite that detonated as a
+   merge-blocker and was "fixed" by flag-gating the epic's only visual verification (4.73M).
 2. Re-read the backlog card (`requirements`, `acceptance_criteria`, `unknowns`, and `definition_of_done` fields).
 3. Build a checklist — one row per item: