TheLastGarden/.planning/phases/01-foundations-and-doctrine/01-07-ci-workflow-SUMMARY.md

---
phase: 01-foundations-and-doctrine
plan: 07
subsystem: ci
tags: [ci, github-actions, pipe-06, minimum-viable, solo-dev, no-ceremony]

# Dependency graph
requires:
  - phase: 01
    plan: 01
    provides: package.json with `ci` script chaining lint + test + validate:assets + build; package-lock.json (committed); Node 22 baseline
  - phase: 01
    plan: 02
    provides: `npm run lint` green (ESLint flat config + boundaries plugin, --max-warnings 0)
  - phase: 01
    plan: 03
    provides: `npm test` green (save layer — checksum, envelope, migrations, db, snapshots, persist, round-trip)
  - phase: 01
    plan: 04
    provides: `npm test` green (content loader) + `npm run build` green (Vite-native content pipeline)
  - phase: 01
    plan: 05
    provides: `npm run validate:assets` exits 0 (Task 1 validator merged; Task 2 north-star images partial — validator passes with 0 assets which is valid)
  - phase: 01
    plan: 06
    provides: `npm test` green (doctrine.test.ts via extended vitest include glob)
provides:
  - .github/workflows/ci.yml — single-job GitHub Actions workflow (49 lines including load-bearing comments) running `npm ci` + `npm run ci` on push to main and pull_request to main; ubuntu-latest; Node 22; actions/setup-node@v4 with cache:'npm'; timeout-minutes:10
affects:
  - "Phase 2: when economy tests + Playwright e2e (PIPE-07) land, they go through the same `npm run ci` script — the workflow file does NOT need to change. If Phase 2 wants Playwright on CI, add `npx playwright install --with-deps chromium` before the `npm run ci` step and update the `ci` script in package.json to include `&& npm run e2e`."
  - "Phase 8: visual regression testing (PIPE-04) will likely require a separate workflow file (matrix runs against multiple OSes / heavier runtime) since it's a different cost profile from this single-job lint/test workflow. Do not bolt it onto ci.yml."
  - "Every Phase 1 success criterion is now structurally enforced on every commit going forward: CORE-10 (Plan 02 lint), CORE-04..09 (Plan 03 + Plan 06 doctrine.test.ts), PIPE-01 (Plan 04 loader.test.ts + build), PIPE-03/AEST-08/AEST-09 (Plan 05 validate:assets + test), PIPE-05 (Plan 06 doctrine.test.ts), PIPE-06 (this workflow), CORE-01 smoke (build)."
  - "Phase 1 partial item: Plan 05 Task 2 (10–20 north-star reference images) still awaits human curation. The validator passes when 0 assets are present (`[provenance] all 0 assets carry valid provenance.`); the CI workflow does NOT depend on the images being present, so it ships green today and will *continue* to be green once the images land (each carrying a valid sidecar)."

# Tech tracking
tech-stack:
  added: []  # no new deps; pure CI configuration
  patterns:
    - "Minimum-viable CI per CONTEXT user pushback: one job, one OS (ubuntu-latest), one Node version (22), no third-party actions beyond actions/checkout@v4 + actions/setup-node@v4. The workflow's purpose is to refuse merges that break the local `npm run ci`, nothing more."
    - "CI script as single source of truth: the workflow runs `npm run ci`, defined in package.json by Plan 01 as `npm run lint && npm run test && npm run validate:assets && npm run build`. Adding new gates (e.g., e2e in Phase 2) is done by editing `package.json scripts.ci`, NOT by editing the workflow file. The workflow stays stable across all future phases."
    - "Cache discipline (RESEARCH CI Pitfall A): `actions/setup-node@v4` with `cache: 'npm'` caches `~/.npm` keyed by `package-lock.json`, never `node_modules/` directly. Caching `node_modules/` is the canonical CI footgun (transitive deps go stale silently)."
    - "Lockfile-strict install: `npm ci` (not `npm install`) refuses to run if `package.json` and `package-lock.json` drift. This is the standard mitigation for solo-dev supply-chain risk in Phase 1 (T-01-08, see plan threat model). `npm audit` as a CI step deferred to Phase 8 launch polish if surface area grows."
    - "Comment-as-doc: the workflow file's leading 18-line comment block enumerates *what is deliberately omitted* (OS matrix, Node-version matrix, test reporters, Codecov, release automation, notification integrations) so a future contributor reading the file knows the omissions are intentional design decisions, not oversights. Per CONTEXT D-07/D-08 doctrine-as-rationale pattern."

key-files:
  created:
    - .github/workflows/ci.yml (49 lines: 18-line header comment block + 4-line `name`/`on` declaration + 27-line `jobs.ci` definition with 4 steps)
  modified: []

key-decisions:
  - "Workflow stays at 49 lines (slightly over the 20-line target from RESEARCH Open Question #4) because the leading comment block is load-bearing context — it explains *why* the omissions are there so a future contributor reading the file does not 'helpfully' add a matrix or Codecov upload that would violate CONTEXT user pushback. The actual YAML logic is ~27 lines."
  - "Node 22 chosen (not 20) per RESEARCH § Environment Availability: 'Node 22 ideal for native crypto.hash; Node ≥ 20 required for recursive readdir; the validator uses readdir without recursive but Node 22 is the modern baseline.' Single-version (no matrix) per CONTEXT user pushback against ceremony."
  - "ubuntu-latest only (no Windows / macOS matrix). PIPE-04 visual regression testing is Phase 8; cross-OS coverage of the *idle game itself* belongs there, not here. Plan 01–06 deliverables are all platform-agnostic (TypeScript, Node, npm)."
  - "Triggers limited to `push` to main and `pull_request` to main. No tag-based release triggers (no releases until Phase 2 ships Season 1 per ROADMAP). No schedule triggers (no cron/canary needs in Phase 1)."
  - "timeout-minutes: 10 chosen as a sensible ceiling: local `npm run ci` runs in ~5s (lint) + ~2.5s (test) + ~0.1s (validator) + ~0.7s (build) = well under 10s for the script proper; with `npm ci` install (~30–60s on fresh CI) the realistic full run is ~1–2min. 10min ceiling catches stuck runs without false-positives on slow GitHub runners."
  - "Workflow does NOT depend on Plan 05 Task 2 (north-star images). The validator passes with 0 assets (`[provenance] all 0 assets carry valid provenance.`); when human curation lands the images, the validator will continue to pass (each new asset will carry a sidecar by definition of the curation gate). This means Phase 1's CI is shippable *now* even with Plan 05 partial."

requirements-completed: [PIPE-06]

# Metrics
duration: 2min
completed: 2026-05-09
---

# Phase 1 Plan 07: CI Workflow Summary

**Single-job `.github/workflows/ci.yml` (49 lines) runs `npm ci` + `npm run ci` on push to main and PR to main; Node 22, ubuntu-latest, actions/setup-node@v4 with `cache: 'npm'`, 10-minute timeout. Local `npm run ci` exits 0 (lint clean, 53 tests pass across 12 files, validator green, build green). PIPE-06 structurally enforced; every Phase 1 automated check now runs on every commit going forward.**

## Performance

- **Plan duration:** ~2 min (single-task plan; the YAML structure was specified verbatim in the plan)
- **Local `npm run ci` runtime (immediately before commit):**
  - lint: <1s (clean, no warnings, --max-warnings=0)
  - test: 2.37s (53 tests / 12 files, all passing)
  - validate:assets: <0.5s (0 assets, all valid)
  - build: 0.66s (tsc -b + vite build)
  - **Total: ~5s** (well under the 30s feedback-latency target from VALIDATION.md)
- **Expected CI runtime on GitHub:** ~1–2 min (dominated by `npm ci` install on fresh runner; the test/lint/build steps remain ~5s)

## What Was Built

### `.github/workflows/ci.yml` (49 lines)

The full file:

```yaml
# Phase 1 — minimum-viable CI per RESEARCH Open Question #4 + CONTEXT user pushback
# against ceremonial workflows (.planning/phases/01-foundations-and-doctrine/01-CONTEXT.md).
#
# On every push to main and every pull request:
#   - npm ci (lockfile-strict install — refuses on package.json drift)
#   - npm run ci (lint + test + validate-assets + build, defined in package.json)
#
# This single job satisfies PIPE-06: Vitest tests run on every CI build.
# Phase 2+ economy tests flow through the same `npm run ci` chain — no workflow change
# is needed when more tests are added.
#
# Deliberately omitted (per CONTEXT user pushback against ceremony):
#   - OS matrix (Linux only is fine; PIPE-04 visual regression testing is Phase 8)
#   - Node-version matrix (one supported version is enough for solo-dev)
#   - Test reporters / Codecov uploads (no coverage requirement in Phase 1)
#   - Release automation (no releases until Phase 2 ships Season 1)
#   - Notification integrations (the project owner reads GitHub directly)

name: ci

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  ci:
    name: lint + test + validate-assets + build
    runs-on: ubuntu-latest
    timeout-minutes: 10

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node 22
        uses: actions/setup-node@v4
        with:
          node-version: '22'
          # Per RESEARCH CI Pitfall A: cache ~/.npm based on package-lock.json,
          # NEVER cache node_modules/ directly (transitive deps go stale).
          cache: 'npm'

      - name: Install dependencies (lockfile-strict)
        run: npm ci

      - name: Run CI suite
        run: npm run ci
```

### Acceptance Criteria — All 11 Pass

| # | Criterion | Result |
|---|-----------|--------|
| 1 | `.github/workflows/ci.yml` exists | OK |
| 2 | Workflow runs `npm run ci` | OK |
| 3 | Uses `actions/setup-node@v4` with `cache: 'npm'` | OK |
| 4 | Does NOT cache `node_modules/` directly (RESEARCH CI Pitfall A) | OK |
| 5 | Uses Node 22 | OK |
| 6 | Runs `npm ci` (lockfile-strict) before `npm run ci` (line 46 < line 49) | OK |
| 7 | Triggers on push to main AND pull_request to main (`branches: [main]` count = 2) | OK |
| 8 | Has sensible `timeout-minutes` (10) | OK |
| 9 | Locally `npm run ci` exits 0 (proves workflow will be green) | OK |
| 10 | Contains comments explaining what was deliberately omitted | OK |
| 11 | Single-job, single-matrix-entry, no third-party actions beyond checkout + setup-node | OK |

## Deviations from Plan

**None — plan executed exactly as written.**

The plan documented the YAML verbatim and the file was authored to match. Pre-flight `npm run ci` was green; post-write acceptance checks all passed; no Rule 1/2/3 fixes needed.

## Authentication Gates

None. CI workflow files require no auth to author or commit; GitHub validates the YAML on push (will happen on the user's next push, not gated on this plan).

## Phase 1 Closure — Structural Enforcement Map

With `.github/workflows/ci.yml` landed, every Phase 1 success criterion is now enforced on every commit:

| Success Criterion | Enforcement | Plan Source |
|-------------------|-------------|-------------|
| 1. Game scaffold builds (CORE-01) | `npm run build` (smoke) | Plan 01 + Plan 04 |
| 2. Round-trip save test passes (CORE-04..09) | `npm test` (12 test files / 53 tests / save layer covers checksum, envelope, migrations, db, snapshots, persist, round-trip) | Plan 03 |
| 3a. CI fails if `src/sim/` imports `src/render/`/`src/ui/` (CORE-10) | `npm run lint` (boundaries plugin) | Plan 02 |
| 3b. CI fails if `/content/**` violates Zod schema (PIPE-01) | `npm test` (loader.test.ts) + `npm run build` (Vite content pipeline build-time) | Plan 04 |
| 3c. CI fails if any AI asset is missing provenance (PIPE-03, AEST-08, AEST-09) | `npm run validate:assets` + `npm test` (validate-assets.test.ts) | Plan 05 (Task 1 done; Task 2 awaits curation — validator passes with 0 assets which is valid) |
| 4. Anti-FOMO + Season 7 end-state docs exist (PIPE-05, UX-13) | `npm test` (doctrine.test.ts — 8 assertions across 2 docs) | Plan 06 |
| 5. North-star reference set + curation gate (AEST-08, AEST-09) | Validator + sidecar gate landed; 10–20 images await human curation (Plan 05 Task 2 — checkpoint:human-verify) | Plan 05 (partial) |
| (Cross-cutting) PIPE-06: Vitest runs on every CI build | `.github/workflows/ci.yml` runs `npm run ci` on push + PR | This plan |

## Phase 1 Open Item Tracking

- **Plan 05 Task 2 (north-star images):** Awaits human curation per the checkpoint. The CI workflow ships green *today* because the validator passes with 0 assets (`[provenance] all 0 assets carry valid provenance.`). When the user curates and commits the 10–20 images, each will carry a valid sidecar by definition of the curation gate, and the validator will continue to pass — no changes to `ci.yml` needed.

## Phase 2 Handoff Notes

When Phase 2 lands:

1. **Adding economy tests:** Drop new `*.test.ts` files anywhere in the repo's existing `vitest` include glob (`src/**/*.test.ts`, `scripts/**/*.test.ts`). They will run automatically as part of `npm test` → `npm run ci` → CI workflow. **No workflow file change needed.**

2. **Adding Playwright e2e (PIPE-07):** Two changes:
   - In `package.json`: extend `scripts.ci` to include `&& npm run e2e` (or chain it however Phase 2 prefers).
   - In `.github/workflows/ci.yml`: add a new step *before* `Run CI suite`:
     ```yaml
     - name: Install Playwright browsers
       run: npx playwright install --with-deps chromium
     ```
     This is the canonical pattern for Playwright on GitHub Actions ubuntu-latest. No matrix needed for Phase 2; visual regression matrix is Phase 8.

3. **Phase 8 visual regression testing (PIPE-04):** Likely warrants a *separate* workflow file (e.g., `.github/workflows/visual-regression.yml`) — different cost profile (multi-OS matrix, snapshot uploads, possibly nightly schedule). Do NOT bolt it onto `ci.yml`; keep `ci.yml` as the fast PR-blocking gate.

## Threat Model — T-01-08 Mitigation Confirmed

The plan's threat model called out T-01-08 (npm install supply-chain compromise via transitive dep) with disposition **mitigate**. The mitigation is in place:

- `package-lock.json` is committed (Plan 01).
- `.github/workflows/ci.yml` uses `npm ci` (not `npm install`), which refuses to run if `package.json` and `package-lock.json` drift.
- This is the standard solo-dev supply-chain mitigation per RESEARCH § Security Domain.
- `npm audit` as a CI step deferred to Phase 8 launch polish if surface area grows (deliberately deferred to keep Phase 1 minimum-viable per CONTEXT user pushback).

## Threat Flags

None. The workflow file introduces no new network endpoints, auth paths, file access patterns, or schema changes at trust boundaries. It only invokes existing `npm` commands that were already in scope.

## Self-Check: PASSED

- File exists: FOUND `.github/workflows/ci.yml`
- Commit exists: FOUND `609d582` (`ci(01-07): minimum-viable GitHub Actions workflow running npm run ci on push + PR (PIPE-06)`)
- All 11 acceptance criteria from PLAN green (see "Acceptance Criteria" table above)
- Pre-flight `npm run ci` exit 0 (lint clean / 53 tests pass / validator OK / build OK)
- No deletions in commit
- No unintended untracked files (only pre-existing `.claude/` local config)