# 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)`