cadence-ui/docs/exec-plans/2026-03-23-harness-foundation.md

Harness Foundation

• Status: completed
• Owner: codex
• Date: 2026-03-23

Goal

Introduce the first harness-engineering layer for Cadence UI so the repository becomes easier for agents to understand, plan against, and validate mechanically.

Scope

• In scope:
  • document the harness workflow
  • add execution-plan conventions
  • expose shared validation suites from one entrypoint
  • add a pull request workflow that runs the PR validation suite
• Out of scope:
  • full worktree orchestration
  • change-aware suite selection
  • fixing pre-existing lint and Storybook smoke issues discovered during baseline review

Constraints

• Keep the existing package, registry, and Storybook workflows intact.
• Avoid introducing a hard dependency on a specific coding-agent CLI.
• Preserve the current release scripts while adding a richer harness path alongside them.

Affected Surfaces

• AGENTS.md
• CONTRIBUTING.md
• README.md
• docs/harness-engineering.md
• docs/exec-plans/*
• package.json
• .github/workflows/harness-validate.yml
• scripts/harness/validate.mjs

Plan

1. Document what harness engineering means for this repository.
2. Add versioned execution-plan guidance and a real example plan.
3. Expose reusable validation suites behind a single script.
4. Run the new PR suite from GitHub Actions.

Validation

• pnpm harness:suites
• pnpm harness:validate:pr -- --dry-run

Baseline findings captured during rollout:

• pnpm test passed
• pnpm typecheck passed
• pnpm lint failed on pre-existing story/test lint issues plus React Compiler hook lint
• pnpm test:e2e:smoke reached a real Storybook drift failure in the button playground flow once browser launch permissions were provided

Status Log

• 2026-03-23 12:18 inspected repo structure, QA stack, CI workflows, and agent guidance
• 2026-03-23 12:24 confirmed test and typecheck pass; found pre-existing lint failures
• 2026-03-23 12:26 reran Playwright smoke outside the sandbox and confirmed one real Storybook smoke failure instead of a harness-only environment failure
• 2026-03-23 12:31 added harness docs, execution-plan conventions, validation script, and PR workflow