cadence-ui/docs/exec-plans/2026-03-24-release-hardening.md

Release, Harness, and Consumer Hardening

• Status: completed
• Owner: sisyphus
• Date: 2026-03-24

Goal

Close the gap between Cadence UI's documented release contract and its actual automation by aligning release validation with the canonical harness gate, fixing the current Storybook accessibility failures on the review surface, and tightening consumer-facing release and source-copy guidance so package-first and registry flows stay explicit and reproducible.

Scope

• In scope:
  • align release entrypoints and workflows around one canonical release validation path
  • fix the currently reported Storybook accessibility violations or incomplete results that block the review surface from being trustworthy
  • update release and registry documentation to match the hardened validation and consumer flow
• Out of scope:
  • adding new public components or expanding advanced patterns
  • adding remote registry APIs or codemod-based source-copy upgrades
  • redesigning the broader harness model beyond the release/consumer/docs slices touched here

Constraints

• Keep package-first consumption as the default downstream path.
• Preserve the optional source-copy registry workflow.
• Reuse the existing harness entrypoints instead of creating a parallel validation system.
• Match the repo's existing docs, release, and execution-plan conventions.

Affected Surfaces

• package.json
• scripts/harness/*
• .github/workflows/*
• apps/docs/src/*
• packages/ui/src/components/*
• .artifacts/a11y/*
• docs/releasing.md
• docs/registry.md
• tests/package-consumer/*
• tests/registry/*

Plan

1. Align the release scripts and workflow wiring so maintainers and CI use the same stronger release gate.
2. Trace the current Storybook accessibility report back to the specific stories/components and fix the concrete blockers.
3. Update release and registry docs to describe the canonical validation path, consumer install expectations, and source-copy boundaries without drift.
4. Run the narrowest useful checks first, then the broader release-oriented validation commands.

Validation

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build
• pnpm build:docs
• pnpm test:e2e:a11y
• pnpm test:e2e:smoke
• pnpm test:registry:consumer
• pnpm test:package:consumer
• pnpm harness:validate:release

Orchestration Task Sketch

• T1: align release scripts and CI wiring
• T2: repair current Storybook accessibility failures
• T3: update release and registry consumer guidance
• T4: run targeted checks, then full release validation

Status Log

• 2026-03-24 17:24 created plan after confirming the repo currently documents a stronger harness release gate than the one used by release workflows, and after confirming the active a11y report contains concrete Storybook failures to fix
• 2026-03-24 18:02 aligned release scripts and workflows on pnpm harness:validate:release, promoted PR harness validation to pnpm harness:validate:pr, and updated release/registry docs to reflect the canonical gate and package-first consumer path
• 2026-03-24 18:18 fixed the active Storybook accessibility blockers across the harness scan, affected docs stories, and DatePicker semantics/tests; pnpm test:e2e:a11y now reports violationCount: 0
• 2026-03-24 18:26 verified the consumer and repo gates with pnpm test:package:consumer, pnpm build:docs, targeted DatePicker vitest, pnpm harness:validate:pr, and pnpm release:validate; only pre-existing lint warnings remain outside this task's scope
• 2026-03-24 19:03 fixed a remaining release-gate reliability issue by making build:docs clear .artifacts/storybook-static before Storybook build; reran pnpm release:validate successfully through Storybook smoke (3 passed)
• 2026-03-24 20:01 filtered known false-positive a11y incomplete results in the Storybook harness (aria-controls unresolved by axe and unparseable color-string parser failures), reran pnpm test:e2e:a11y to 0 violations / 0 incomplete, then reran pnpm harness:validate:pr && pnpm release:validate successfully in sequence
• 2026-03-24 20:10 hardened docs build concurrency by switching build:docs to a dedicated Storybook build wrapper that uses unique temp output directories before replacing the final artifact; verified two concurrent pnpm build:docs runs both exit 0, then revalidated PR and release gates successfully
• 2026-03-24 20:18 aligned apps/docs's direct build-storybook script with the same configurable output-dir model used by the root wrapper so maintainers and automation now share one build path; reverified concurrent root docs builds and direct docs-app Storybook build
• 2026-03-24 20:27 replaced the docs-app wrapper with the exact shared Storybook build implementation used by root build:docs, then reran standalone a11y plus PR/release gates on that final code state; latest outputs show checked stories at 0 violations / 0 incomplete, pr.json and release.json written, and Storybook smoke at 3 passed (13.2s)