diff --git a/docs/exec-plans/2026-03-24-release-hardening.md b/docs/exec-plans/2026-03-24-release-hardening.md new file mode 100644 index 0000000..ef19f91 --- /dev/null +++ b/docs/exec-plans/2026-03-24-release-hardening.md @@ -0,0 +1,107 @@ +# 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)` diff --git a/docs/registry.md b/docs/registry.md index acc6c3a..a479109 100644 --- a/docs/registry.md +++ b/docs/registry.md @@ -43,7 +43,7 @@ The generated index includes transitive local helpers, not just component entryp component starts importing a shared file such as `packages/ui/src/lib/icons.tsx`, rebuild the index before merge so source-copy consumers receive the full dependency graph. -To validate the end-to-end consumer flow locally: +To validate the end-to-end source-copy consumer flow locally: ```bash pnpm test:registry:consumer @@ -52,6 +52,15 @@ pnpm test:registry:consumer That smoke test creates a temporary app, runs the registry installer, installs the required dependencies, and verifies that the copied source both typechecks and builds. +For the broader release path, the canonical release gate also includes registry validation and +both consumer smoke suites: + +```bash +pnpm harness:validate:release +``` + +Use that gate before release work that changes package, docs, or consumer-facing behavior. + ## Consumer install flow Choose this flow when: diff --git a/docs/releasing.md b/docs/releasing.md index ee653e3..d290b14 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -87,21 +87,26 @@ Because `@ai-ui/ui` and `@ai-ui/tokens` are fixed together, version bumps move a ## Local maintainer commands -Run the release validation suite locally with: +Run the canonical release gate locally with: ```bash -pnpm release:validate +pnpm harness:validate:release ``` -That command currently runs: +`pnpm release:validate` remains as a convenience alias to the same gate. + +The canonical release gate runs: - lint - typecheck - package unit tests - package builds +- Storybook build +- Storybook accessibility validation - registry metadata validation - source-copy consumer smoke - package consumer smoke +- Storybook smoke coverage Create a versioned release change with: @@ -126,7 +131,7 @@ pnpm release:publish The automated release sequence is now: 1. A product or package PR merges to `main` with a changeset. -2. `Release Version PR` runs on `main`, executes `pnpm release:validate`, and opens or updates a version PR via Changesets. +2. `Release Version PR` runs on `main`, executes `pnpm harness:validate:release`, and opens or updates a version PR via Changesets. 3. A maintainer reviews and merges that version PR. 4. `Create Release Tag` detects the package version change on `main` and creates `cadence-ui-vX.Y.Z`. 5. `Publish Packages` runs on the tag push, validates the tagged commit again, and publishes `@ai-ui/ui` and `@ai-ui/tokens`. @@ -151,7 +156,7 @@ artifact for package consumers. `Release Version PR` runs on pushes to `main` and: - installs dependencies -- runs `pnpm release:validate` +- runs `pnpm harness:validate:release` - opens or updates the version PR with `pnpm release:version` ### Tag workflow @@ -166,7 +171,7 @@ artifact for package consumers. `Publish Packages` runs on `cadence-ui-v*` tags and: - verifies the tag matches the package version -- runs `pnpm release:validate` +- runs `pnpm harness:validate:release` - publishes the packages with `NPM_TOKEN` ## Required secrets