Simplify harness to the doc-prescribed minimum

AGENTS.md

@@ -1,82 +1,51 @@
 # AGENTS.md
 
-This repository is a React Native (Expo) project organized around **harness
-engineering** — a discipline that treats the repo as the system of record for
-AI agents and humans alike. Keep this file short. Use it as the routing layer
-into the system-of-record docs, not as a giant instruction dump.
-
-> If a fact about how to work in this repo is not in a file, it does not
-> exist. Add or update a file before you act on memory.
-
-## Startup Workflow
-
-Before changing code, in this order:
-
-1. Confirm the repo root with `pwd`. It must end in `/rn-harness`.
-2. Read `claude-progress.md` for prior-session handoff notes and known issues.
-3. Read `feature_list.json` to see which features are `done`, `in_progress`,
-   or `blocked`.
-4. Read `docs/ARCHITECTURE.md` for the layer model and dependency rules.
-5. Read `docs/HARNESS.md` for the working contract and definitions of done.
-6. Review recent commits: `git log --oneline -10`.
-7. Run `./init.sh` and wait for it to complete cleanly.
-8. If the baseline (`npm run verify`) is broken, **repair the baseline first**.
-   Do not start new work on a red baseline.
-9. Pick the highest-priority feature whose `status` is `in_progress` or the
-   next `todo` one. Work on **only that feature** until it is verified or
-   explicitly blocked. (WIP = 1.)
-
-## Routing Map
-
-- `docs/ARCHITECTURE.md` — domain map, layer model, dependency rules
-- `docs/HARNESS.md` — working contract, DoD, WIP=1, session lifecycle
-- `docs/RN_PLATFORM.md` — Expo, Metro, Hermes, native modules, EAS rules
-- `docs/VERIFICATION.md` — what runs in `npm run verify` and why
-- `docs/UI.md` — design system, theming, accessibility, RTL
-- `docs/SESSION.md` — end-of-session checklist
-- `docs/WHY_HARNESS_FOR_RN.md` — why this discipline pays off for React Native
-- `feature_list.json` — scope boundaries, machine-readable
-- `claude-progress.md` — durable session log
-
-## Hard Rules
-
-- **WIP = 1.** Touch one feature at a time. Do not bundle "while I'm here"
-  fixes into an unrelated feature.
-- **No declaring victory without evidence.** Code inspection ≠ done. Tests must
-  pass, the app must start, and the feature's verification steps from
-  `feature_list.json` must each be checked.
-- **Do not edit `ios/` or `android/` folders.** This project is managed
-  workflow (Expo prebuild). Native changes go through `app.json`, config
-  plugins, or `expo-build-properties` — see `docs/RN_PLATFORM.md`.
-- **Pin behavior to versions.** Expo SDK 54 is current. When in doubt, read
-  the exact versioned docs at https://docs.expo.dev/versions/v54.0.0/ before
-  writing code that depends on platform APIs.
-- **Do not skip Metro / type / lint failures.** Resetting caches is not a fix;
-  it is a diagnosis tool. If a fix requires clearing the Metro cache, document
-  *why* in `claude-progress.md`.
-
-## Definition Of Done
-
-A change is "done" only when **all** of the following are true:
-
-- Target behavior is implemented and the verification steps in
-  `feature_list.json` for the feature have each been performed.
-- `npm run verify` passes from a clean clone (lint + typecheck + unit tests).
-- The app starts via `npm run start` without red error overlays on at least
-  one platform (iOS sim, Android emulator, or Web — record which).
-- Docs affected by the change are updated in the same session.
-- `feature_list.json` is updated: status moved to `done`, `passes: true`,
-  and the matching commit SHA recorded.
-- `claude-progress.md` reflects the new state and lists the next action.
-
-## End Of Session
-
-Before ending a session, run through `docs/SESSION.md`. The shortest version:
-
-1. `npm run verify` — must be green or have a documented red-line waiver.
-2. Update `feature_list.json` and `claude-progress.md`.
-3. Commit small, coherent changes — never `git add -A` after a long session
-   without reviewing the diff.
-4. Run `npm run harness:clean-state` and address anything it flags.
-5. Leave a one-paragraph "next action" at the top of `claude-progress.md` so
-   the next session can begin without re-reading the world.
+This is a React Native (Expo SDK 54) project organized around [harness
+engineering](https://walkinglabs.github.io/learn-harness-engineering).
+Keep this file short — it's a router into the system-of-record docs,
+not an instruction dump.
+
+> If a fact about how to work in this repo isn't in a file, it doesn't
+> exist. Add it before you act on memory.
+
+## Startup workflow
+
+1. `pwd` — confirm repo root ends in `/rn-harness`.
+2. Read `PROGRESS.md` (small) — recover state, see the next best step.
+3. Read `feature_list.json` — see which features are `done`,
+   `in_progress`, `blocked`.
+4. `./init.sh` — fail loudly if the foundation is broken.
+5. `npm run verify` — baseline must be green before new work.
+6. Pick the highest-priority `in_progress` feature, else the next
+   `todo`. Work only on that until verified or blocked. **WIP = 1.**
+
+## Routing
+
+| Doc | What it covers |
+| --- | --- |
+| `docs/HARNESS.md` | working contract, naming standard, DoD |
+| `docs/SESSION.md` | end-of-session checklist, PR template |
+| `docs/ARCHITECTURE.md` | layer model, folder map |
+| `docs/RN_PLATFORM.md` | Expo / Metro / Hermes / EAS rules |
+| `PROGRESS.md` | current state, next steps |
+| `DECISIONS.md` | append-only design decisions |
+| `feature_list.json` | machine-readable scope |
+| `.maestro/README.md` | E2E flow authoring |
+
+## Hard rules
+
+- **WIP = 1.** One feature at a time.
+- **No declaring victory without evidence.** `feature_list.json[].verification`
+  list must have been performed before flipping to `done`.
+- **Don't edit `ios/` / `android/`.** Native config goes through
+  `app.json` + config plugins. See `docs/RN_PLATFORM.md`.
+- **Pin behavior to versions.** Expo SDK 54 — read
+  https://docs.expo.dev/versions/v54.0.0/ when in doubt.
+- **Don't skip type / lint / test failures.** Reset Metro cache only
+  as diagnosis, never as fix.
+
+## End of session
+
+Run `docs/SESSION.md`. In one sentence: verify green, update
+`PROGRESS.md` + `feature_list.json`, commit, open a PR if the branch
+is reviewable, run `npm run harness:clean-state`.

CLAUDE.md

@@ -1,43 +1,26 @@
 @AGENTS.md
 
-# CLAUDE.md — Claude Code entry point
+# CLAUDE.md
 
-The `@AGENTS.md` directive above imports the operating manual. Everything
-in `AGENTS.md` applies to Claude verbatim. The notes below are Claude-Code
-specific.
+`@AGENTS.md` imports the operating manual. Everything in `AGENTS.md`
+applies. The notes below are Claude-Code-specific.
 
 ## Before your first tool call
 
-1. Read `claude-progress.md` for the **Next action** block.
-2. Read `feature_list.json` and pick exactly one `in_progress` or `todo`
-   feature. If multiple `in_progress` features exist, that is a harness
-   violation — fix it (move all but one back to `todo`) before doing
-   anything else.
-3. Run `./init.sh`. If it fails, fix the foundation before touching
-   product code.
+1. Read `PROGRESS.md` for *Next steps*.
+2. Read `feature_list.json`. Pick exactly one `in_progress` or `todo`
+   feature. Multiple `in_progress` is a harness violation — fix it
+   before doing anything else.
+3. `./init.sh`. If it exits non-zero, fix the foundation first.
 
-## When to ask, when to act
+## When to ask vs. act
 
-This repo's harness was designed so most decisions are already encoded in
-files. Before asking the user a clarifying question, check:
+Most decisions are already in files. Before asking the user, check:
 
 - `docs/HARNESS.md` — working contract
 - `docs/ARCHITECTURE.md` — layer rules
 - `docs/RN_PLATFORM.md` — Expo / Metro / Hermes rules
-- `docs/VERIFICATION.md` — what counts as "done"
-- `docs/E2E_TESTING.md` — how to verify simulator builds
+- `DECISIONS.md` — what was already decided and why
 
-If the answer is genuinely not in any file, that itself is a defect — fix
-the missing doc in the same session you ask the question.
-
-## Why this repo has so much scaffolding
-
-It follows [harness
-engineering](https://walkinglabs.github.io/learn-harness-engineering): an
-empirical discipline showing that *environment design* affects long-horizon
-agent reliability more than model capability does. The five subsystems
-(instructions / state / verification / scope / lifecycle) and the
-file-by-file conventions are the cheapest known way to keep agents from
-overreaching, under-finishing, or declaring victory too early.
-
-See `docs/WHY_HARNESS_FOR_RN.md` for the React-Native–specific case.
+If the answer isn't in any file, that's a defect — fix the missing doc
+in the same session you ask the question.

DECISIONS.md

@@ -0,0 +1,71 @@
+# DECISIONS.md
+
+> Append-only log of non-obvious project decisions, per Lecture 05.
+> Format: `## YYYY-MM-DD — short title` then a few lines of *what / why /
+> rejected alternative / constraints*. Newest at the bottom.
+
+## 2026-05-19 — Expo (managed) over bare React Native CLI
+
+- **What:** project scaffolded with `create-expo-app`; managed workflow,
+  no `ios/`/`android/` in git.
+- **Why:** Expo SDK 54 covers our needs; EAS for builds; avoids native
+  drift between agent sessions (which is exactly what harness
+  engineering exists to prevent).
+- **Rejected:** bare RN CLI — more native surface area, more places for
+  silent drift.
+- **Constraint:** native modules need a config plugin or a dev build;
+  no direct edits to native dirs.
+
+## 2026-05-19 — Expo Router for file-based navigation
+
+- **What:** routes live in `app/`, navigated by file path.
+- **Why:** matches the Next.js mental model most agents already have.
+- **Rejected:** React Navigation only — works, but more boilerplate.
+
+## 2026-05-19 — Maestro for E2E (not Detox, not Playwright)
+
+- **What:** Maestro is the e2e tool wired into `feature_list.json`
+  verification lists.
+- **Why:** single-binary YAML runner; flows are trivial for agents to
+  author; output (logs + screenshots + JUnit XML) plugs straight into
+  the harness.
+- **Rejected:** Playwright (web-only — no Hermes coverage); Detox (more
+  power but heavy per-feature wiring).
+
+## 2026-05-19 — Sim boot helpers separate from `npm run ios/android`
+
+- **What:** `scripts/sim-ios.sh` and `scripts/sim-android.sh` boot the
+  simulator only; `npm run ios/android` does build+install+launch.
+- **Why:** booting and building are different concerns. Agents should
+  be able to warm a sim once and run multiple flows against it.
+
+## 2026-05-19 — Naming standard: `<category>-<NNN>` everywhere
+
+- **What:** feature IDs in `feature_list.json`, branch names
+  (`<type>/<feature-id>-<slug>`), and commit subjects
+  (`<type>(<feature-id>): …`) all carry the same ID.
+- **Why:** a single `git log --grep='(ui-002)'` returns the full story.
+  Drift between forms of state erodes the "repo is system of record"
+  principle (Lecture 03).
+- **Enforced:** `scripts/feature-list-check.js` validates IDs against
+  `^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*-\d{3}$`.
+
+## 2026-05-19 — Removed speculative testing-library deps
+
+- **What:** dropped `@testing-library/jest-native` and
+  `@testing-library/react-native` from `devDependencies`.
+- **Why:** added for `ui-001`/`ui-002` render tests that don't exist
+  yet; ERESOLVE'd against React 19.1 (Expo SDK 54). Re-add at the right
+  version when the consuming feature starts.
+
+## 2026-05-19 — Split `claude-progress.md` into PROGRESS.md + DECISIONS.md
+
+- **What:** the bloated single-file progress log is gone; replaced with
+  a ~25-line `PROGRESS.md` and this append-only `DECISIONS.md`.
+- **Why:** Lecture 05's actual prescription is two files. The combined
+  file caused a conflict on every parallel-branch merge because
+  *Current State* / *Next Action* / *Sessions log* / *Decisions* all
+  changed on every branch. Decisions are append-only by date — they
+  almost never conflict when separated. Per-branch session notes belong
+  in the PR description, not in a shared file.
+- **Rejected:** keeping one file; one file per branch (fragments state).

PROGRESS.md

@@ -0,0 +1,31 @@
+# PROGRESS.md
+
+> Per Lecture 05. Tiny on purpose. Decisions live in `DECISIONS.md`;
+> per-branch session notes live in the PR description. This file's only
+> job: tell the next session **what's the next best step**.
+
+## Current state
+
+- Trunk: `main` at the latest commit
+- Baseline: `npm run verify` green
+
+## Completed
+
+- `harness-001` — Initial harness setup (PR #1, merged)
+- `e2e-001` — Maestro end-to-end verification (PR #2, merged)
+
+## In progress
+
+- `harness-002` — Simplify harness to doc-aligned form (this branch)
+- `ci-001` — GitHub Actions for harness checks (PR #3, open)
+
+## Known issues
+
+- None.
+
+## Next steps
+
+1. Land this PR (`chore/harness-002-simplify`).
+2. Rebase PR #3 on top; update its `harness-ci-checks.sh` to point at
+   `PROGRESS.md` instead of the deleted `claude-progress.md`.
+3. Pick up `ui-001`.