# Ticket 0.6 — CI/CD Pipeline

**Phase**: 0 — Project Scaffolding
**Priority**: High
**Depends on**: 0.1, 0.3

## Description

Set up continuous integration via GitHub Actions. Ensures every push and PR is validated with type checking, linting, unit tests, and E2E tests. Also configures pre-commit hooks via lefthook for local developer feedback.

## Acceptance Criteria

### AC1: GitHub Actions workflow runs on every push and PR

```gherkin
Given a .github/workflows/ci.yml file exists
When a commit is pushed or a PR is opened
Then the CI pipeline runs automatically
And it reports pass/fail status on the PR
```

### AC2: CI pipeline steps

```gherkin
Given the CI pipeline runs
Then it executes these steps in order:
  1. Checkout code
  2. Enable corepack and install pnpm
  3. Install dependencies (`pnpm install --frozen-lockfile`)
  4. Type check with TypeScript 7 (`npx tsgo --noEmit`)
  5. Lint and format check (`pnpm lint`)
  6. Run unit and fixture tests (`pnpm test -- --run`)
  7. Build the project (`pnpm build && pnpm build:frontend`)
  8. Install Playwright browsers
  9. Run E2E tests (`pnpm test:e2e`)
And each step fails fast (stops pipeline on first failure)
And the pipeline uses Node.js 22.x
```

### AC3: Caching for fast CI runs

```gherkin
Given the CI pipeline runs
When pnpm dependencies haven't changed
Then the node_modules are restored from cache
And the pnpm store is cached between runs
And Playwright browsers are cached between runs
And the typical CI run completes in under 3 minutes
```

### AC4: Pre-commit hooks

```gherkin
Given lefthook is configured (lefthook.yml in project root)
When a developer runs `git commit`
Then lefthook runs before the commit:
  - `biome check --staged` (lint + format only staged files)
  - `tsgo --noEmit` (type check)
And the commit is blocked if either check fails
And the hooks are installed automatically via `pnpm install` (via prepare script)
```

### AC5: Branch protection recommendations

```gherkin
Given the CI pipeline is operational
Then the README documents recommended branch protection:
  - Require CI to pass before merge
  - Require up-to-date branches
  - Require at least 1 review
```

## Testable Components

| Component | Test Type | What to Assert |
|-----------|-----------|----------------|
| CI workflow YAML | Unit | Valid GitHub Actions syntax, correct steps and order |
| lefthook config | Unit | Valid YAML, correct hook commands |
| CI pipeline | Fixture | Workflow runs successfully on a clean checkout |
| Pre-commit hooks | Fixture | Hooks block commits with lint errors |

## Files to Create

- `.github/workflows/ci.yml` (GitHub Actions workflow)
- `lefthook.yml` (pre-commit hook configuration)
- Update `package.json` with `"prepare": "lefthook install"` script

## Notes

- **lefthook** is preferred over husky/lint-staged for its speed and simplicity
- Add `@evilmartians/lefthook` to devDependencies
- The CI workflow should also run on `main` branch pushes to catch any issues from direct commits
- Consider adding a separate workflow for release/publish when the project is ready
- Playwright browsers need to be installed in CI — use `npx playwright install --with-deps chromium` (chromium only, not all browsers)
- The `--frozen-lockfile` flag ensures CI uses the exact dependency versions from `pnpm-lock.yaml`
