# 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