@joshuafolkken/kit 1.872.0

package/prompts/review.md

@@ -0,0 +1,217 @@
+# Code Review Prompt
+
+This document is the review **policy**: which level a change is reviewed at, how many rounds a review
+runs, and what happens to a finding after the cap. Two other documents hold the rest, and this file
+points to them rather than restating them:
+
+- The **rubric** the reviewer applies — the severity tests, the nine categories, the output format and
+  the stop conditions — is `prompts/review-rubric.md`, handed to `/code-review` by
+  `pnpm josh review:brief`.
+- The **orchestration** around a review — how the gate runs beside it, when the pull request opens, how
+  the merge is issued — is `.claude/skills/workflow-commands/chain-rule.md` → "Orchestration facts
+  single-sourced here".
+
+---
+
+## When to run
+
+- **Pre-commit self-review** (implementing session, inline): before every `git commit` on a feature
+  branch — scope: the staged diff (`git diff --staged`), level from
+  `pnpm josh review:brief --level-only`.
+- **Workflow review step** (same session, inline): the last stage of the verification gate in `fullrun`
+  / `halfrun` / `backlogrun`, driven by the brief `pnpm josh review:brief` prints. Round 1 runs before the
+  commit — scope: `git diff main`. Round 2 runs after it, beside the CI the commit started
+  (`.claude/skills/workflow-commands/chain-rule.md` → "The pull request opens between the rounds, so CI
+  runs beside round 2").
+
+The workflow review uses the `reviewer` role profile printed by `pnpm josh review:brief`. Pass its
+model and effort explicitly to the review subagent; do not substitute the review level for effort.
+
+Re-run after applying fixes until **no high or medium findings remain — or until two reviews have run
+in total, the first included — whichever comes first.** The cap below is not optional. The second round
+is a verification pass over the fixes, not the first review again
+(`prompts/review-rubric.md` → "The second round is a verification pass, not a second full review").
+
+---
+
+## Review level (decided by `pnpm josh review:brief --level-only`, never by judgement)
+
+**Run `pnpm josh review:brief --level-only` and use what it prints.** It reads the changed paths and
+answers `low` or `medium`; `--staged` classifies the staged diff instead of the branch diff, and
+`--json` adds the reason. Inside a workflow, `pnpm josh review:brief` prints the same level on its first
+line and the rest of the brief with it.
+
+```bash
+pnpm josh review:brief --level-only            # the branch diff
+pnpm josh review:brief --level-only --staged   # the staged diff
+```
+
+**The level is decided from the changed paths and nothing else.** "This one is small" is a judgement
+made under cost pressure, and cost pressure resolves it toward "small" exactly when a defect is most
+likely to be shipped. A rule an agent applies from memory is a rule an agent can talk itself out of;
+one it has to run answers the same way every time.
+
+| Every changed path is…                                                                   | Level    | Rounds                  |
+| ---------------------------------------------------------------------------------------- | -------- | ----------------------- |
+| **inert** — `.editorconfig`, `.gitignore`, `LICENSE`, `CHANGELOG.md`, `*.code-workspace` | `low`    | 1                       |
+| anything else                                                                            | `medium` | up to 2 (the cap below) |
+
+**One non-inert path decides the whole change.** A review reads the change, not a subset of it, so
+there is no per-file level. An empty diff also takes `medium` — answering `low` to "nothing changed"
+would hand a reduced level to a caller that failed to read the diff.
+
+**Three things that look inert are not.** `.vscode/**`, `.gitattributes` and `.prettierignore` are all
+in `package.json`'s `files` and are written into every consumer project by `josh init` / `josh sync`,
+so a defect in one reaches a consumer and is reviewed at `medium` like any other shipped file.
+
+**Documentation is not inert either, and that is deliberate.** `CLAUDE.md`, `prompts/**`, `.claude/**`
+and `docs/**` are all reviewed at `medium`. The "Non-runtime updates" exception in `CLAUDE.md` exempts
+them from _testing_ — which asks whether an automated test could have caught the defect — while this
+asks whether a human reading the diff is the only thing that can. Measured on joshuafolkken/kit#963 and
+#965, both documentation-only by that classification: a `medium` review found ten real defects in each
+— pointers into sections that had been removed, and citations naming the wrong file, in artifacts
+distributed to every consumer — that nothing else would have caught.
+
+**A confirmed High blocks regardless of round count**, and the round cap below does not change that.
+
+---
+
+## Review round cap (2 rounds)
+
+The severity rule in the rubric is not a stopping condition on its own. Every fix creates new surface,
+and a review whose scope is the whole change finds something in it — so the loop is bounded by how much
+new code the fixes produce, which is unbounded.
+
+**Two rounds is the ceiling, not the schedule.** Whether the second one is due at all is
+`pnpm josh review:round2`'s answer — "When round 2 is skipped entirely, and when it is not" below is
+the single source of that condition (joshuafolkken/kit#1433).
+
+This is measured, not theorized. On joshuafolkken/kit#854 four rounds produced 18 findings; on #855
+two rounds produced 19. Almost none of them was a repeat: each round found new things, and many of
+those were about code the **previous round's fix** had just written. Two rounds of that is diligence; a
+third is the review chasing its own tail.
+
+### A merge-conflict resolution review is not one of the two
+
+**When `pnpm josh followup` reports `PR checks failed (merge conflict)`, the child resolves the conflict
+in its own lane and reviews the resolution — and that round does not count against the cap**
+(joshuafolkken/kit#1623). The cap bounds re-reading _the change under review_; a resolution review reads
+a different subject — not the change, but what merging a moved `main` into it did.
+`.claude/skills/workflow-commands/backlogrun-lanes.md` → "Conflicts are not predicted" is the single source of
+the procedure and of the four conditions under which the run steps back instead of resolving.
+`pnpm josh review:attest --check` must answer `ok` before the merge is re-issued, and a confirmed High
+parks the child rather than buying it a further round.
+
+### When round 2 is skipped entirely, and when it is not
+
+**Two rounds is the ceiling; whether the second round runs at all is a command's answer, not a reading
+of a list** (joshuafolkken/kit#1433):
+
+```bash
+pnpm josh review:round2 --round-1-closed   # → required | skip ; the reason on stderr
+```
+
+**Ask it once round 1's fixes are in and before the commit.** Pass `--round-1-closed` only where every
+round-1 High/Medium finding actually closed — by a fix in this working tree, or as a verified false
+positive — and none was filed or deferred. **Without the flag the answer is `required`**, which is also
+what the command answers to every uncertainty it meets, a missing round-1 snapshot included.
+
+**`skip` has exactly two arms, and both are states in which round 1's fix code needs no review**
+(joshuafolkken/kit#1222 — the round exists because round 1's fix code is otherwise unreviewed):
+
+| Arm                    | What it is                                                                                                                   |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| **A — no fix code**    | The fix delta is empty: round 1's findings closed without an edit, so there is no unreviewed fix code                        |
+| **B — inert fix code** | Every path in the fix delta is inert by the review-level classification above — neither executing, instructing, nor shipping |
+
+**Neither arm weakens the standard.** A round-1 High/Medium that did not close is not a closed finding,
+so the flag is not passable; the cap is still two rounds; and a confirmed High still blocks the merge.
+**The wider line joshuafolkken/kit#1433 proposed — exempting anything that is not a runtime code path —
+is not adopted**: a documentation-only diff is exactly where the review is the only detector (the #963 /
+#965 measurement above), so a prompt fix answers `required`.
+
+**A skipped round is recorded on the Issue**, so the condition stays auditable and can be withdrawn if
+a defect is later traced to a skipped delta:
+
+1. Label the Issue `review-round2-skipped`, created once per repository:
+   `gh api repos/{owner}/{repo}/labels -f name=review-round2-skipped -f color=c5def5 -f description="Review round 2 was skipped under the condition in prompts/review.md" --silent 2>/dev/null || true`,
+   then `gh api repos/{owner}/{repo}/issues/<N>/labels -f 'labels[]=review-round2-skipped'`.
+2. Post an Issue comment under the heading `## Round 2 skipped`, naming **which arm fired** and quoting
+   **the reason line the command printed**, verbatim.
+
+### Three-way disposition after the cap
+
+**After the second round, place every remaining non-High finding in exactly one of three exits, decided
+from what the finding is rather than from the filer's discretion** (joshuafolkken/kit#1469). **The
+default exit is branch 3, and branch 2 has to be earned**. Read them in order — branch 1 where the fix is
+trivial and local, branch 2 only where the finding clears the bar it names, branch 3 for everything
+left, which is most of them. "It might matter later" is branch 3.
+
+1. **Fix it in place.** The finding closes in a few lines inside a file the diff already touches, with
+   no design judgement — a stale comment, a name, an unused export. **A fix-in-place never starts a new
+   review round**: the fix widens the diff, so a naive re-review would re-open the loop the cap just
+   closed. The fix must stay **inside a file the diff already changed** and carry **no design decision**;
+   a finding that cannot close under both limits is filed, not fixed in place.
+2. **File it as an Issue.** The finding is a **confirmed defect that reaches a runtime code path** —
+   both halves, and neither on its own. Confirmed means the failure scenario is stated in concrete
+   inputs and state. **Reaching is read exactly as the rubric's Severity test 1 reads it** — a runtime
+   code path, a distributed artifact a consumer reads, or the verification that guards either — so in a
+   repository whose product is its distributed documents, a defect in one of those is a branch-2 finding
+   like any other. **The reaching half is not a judgement**: `pnpm josh disposition <path>` answers
+   `runtime` / `non-runtime` from the finding's paths, sharing the same inert set the review level uses,
+   so only "is the defect confirmed" is left to decide. **"It needs a decision" is no longer a branch-2
+   condition on its own**: a design question with no defect under it takes branch 3.
+3. **Drop it with a one-line note in the PR body.** **This is the default, and it takes everything the
+   other two branches did not**: a Low that does not reach the user, and every remaining finding that is
+   neither closable in place nor a confirmed runtime defect — a design preference or an unproven
+   suspicion included. **The note is not optional**: one line naming the finding and why it was dropped
+   is what keeps a dropped finding auditable rather than invisible.
+
+**What it costs, and why that is the right trade.** A dropped finding that later turns out to matter is
+re-found by the next review of that code, at the price of one round it would have paid anyway. A filed
+finding that never mattered is carried forever — placed in an epic, offered by `epic:next`, read by
+everyone who scans the backlog. The two errors are not symmetric, and the old default was on the
+expensive side of them.
+
+**Findings that reduce to one root judgement are filed as one Issue, not several** — a single follow-up
+Issue with a section per symptom (`## 現象 1` / `## 現象 2`).
+
+Only branch 2 files an Issue. What follows applies to that branch.
+
+- **A finding routed to branch 2 is filed as a follow-up Issue referencing the current one, and the
+  current Issue completes.** (A confirmed High is not a branch-2 finding: it blocks the merge rather
+  than being deferred — see below.)
+- **Filing does not end at the Issue.** `epic:next` only ever offers a child the task list of an epic
+  names, so an Issue in no epic is never handed to a running `backlogrun` — the deferred finding is parked
+  forever, which reads the same from the backlog. **The three steps run inside the CI wait, not before
+  the commit.** Where the run opens a pull request — `fullrun`, `backlogrun` — they go after
+  `pnpm josh git -y` and before `pnpm josh followup`; where it does not — `halfrun`, or a standalone
+  pre-commit self-review — they run as soon as the disposition is decided. **The chain may run in a
+  delegated unit** — `pnpm josh delegate followup-filing` (joshuafolkken/kit#1892).
+- **When the round files a second follow-up, run `pnpm josh issue:fold` first.** Several findings from
+  one review fold into one Issue by default — the filing-time counterpart to the split assessment,
+  reading the same two questions (`.claude/skills/workflow-commands/split-assessment.md` → "The same
+  two questions decide the filing-time fold"). `pnpm josh rule:guard` refuses the second `gh api …
+issues` call until it is folded; the first filing asks nothing.
+
+  1. File the follow-up Issue referencing the current one, tagged `route:review-cap`:
+     `gh api repos/{owner}/{repo}/issues -f title="<title>" -f 'labels[]=route:review-cap' -f 'labels[]=depth:<n>' -f body="<body referencing the current Issue>"`.
+  2. Run `pnpm josh epic:bundle <new>` — **before the current Issue closes.** The candidate search reads
+     open issues only, so once the parent has closed the command answers `none` permanently.
+  3. Act on its answer. **`epic:bundle` recommends and writes nothing**, so acting means running the
+     write command yourself — never a hand edit of the epic body, which leaves the task list and the
+     `blocked-by` relations disagreeing and `epic:next` returning `error`.
+
+  | Answer                                                                                            | Do                                                                                                                                                                                                                                                                                                                                | Tier                    |
+  | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+  | `add_to_epic`                                                                                     | `pnpm josh epic --add <E> <new>` — add `--before <M>` / `--after <M>` when the relation carries an order                                                                                                                                                                                                                          | **A — no confirmation** |
+  | `create_epic`                                                                                     | `pnpm josh epic "<title>" <new> <other> [--ordered]`                                                                                                                                                                                                                                                                              | **A — no confirmation** |
+  | `ask` — candidates spread across two or more epics                                                | **Choose the epic you recommend, run its write command, and record the decision** — what was taken, what was rejected, why — on both the new Issue and that epic's `## Decisions`. This does not stop a run and does not park a child (joshuafolkken/kit#1339); stop only where the two epics are genuinely too close to separate | **A — no confirmation** |
+  | `none`                                                                                            | Nothing                                                                                                                                                                                                                                                                                                                           | —                       |
+  | **The command could not answer** — non-zero exit, or **any** ⚠ warning above `Nothing to bundle.` | Stop and report, naming what it said. **A `none` printed after such a warning is not "nothing to bundle"** — the search was incomplete                                                                                                                                                                                            | —                       |
+
+- **A confirmed High is never deferred.** A real defect does not ship because a round counter ran out,
+  so a standing High blocks the merge — never fixed-in-place, filed, or dropped as one of the three
+  exits. If a High is still standing after the second round, do not start a third: stop, send a
+  `confirmation` Telegram, and put the scope back to the user, where splitting the Issue is usually the
+  answer.

package/prompts/sonar-hotspot-handling.md

@@ -0,0 +1,77 @@
+# SonarCloud Hotspot Handling (project-local extension)
+
+<!-- cspell:words hotspot Hotspot hotspots Hotspots NOSONAR -->
+
+This guide extends the collaboration workflow with a project-local procedure for handling SonarCloud Security Hotspots. It is kept out of the upstream-synced `prompts/collaboration-workflow/` topics so those stay identical across the projects that consume them.
+
+AI tools cannot perform OAuth browser login to SonarCloud, so this guide assumes public-API and config-based actions as the primary path.
+
+## Quality Gate enforcement (CI blocks PRs)
+
+The distributed `.github/workflows/sonar-qube.yml` runs the SonarCloud scan with
+`-Dsonar.qualitygate.wait=true`. The scanner waits for SonarCloud to evaluate the project's
+Quality Gate and **fails the `SonarQube` job — a required PR check — when the gate is red**, so a
+PR that introduces a finding cannot be merged green. This is the single enforcement point:
+`josh followup` does **not** scan SonarCloud findings (it only scans CodeRabbit / Claude Review
+comments), but it **does** wait on the required `SonarQube` CI check, so a red gate also blocks the
+`followup` merge. Consumers pick the workflow up verbatim via `josh sync`; do not re-implement the
+gate per consumer.
+
+### New Code vs Overall Code semantics
+
+SonarCloud's default **Sonar way** Quality Gate evaluates **New Code only** — conditions
+(new bugs, new code smells above the Maintainability rating, new coverage/duplication) apply to
+lines changed in the PR's New Code period, not the whole codebase. Consequences:
+
+- A PR is blocked when it **introduces or modifies** code that trips a condition — this is what
+  catches the recurring Maintainability `0 -> 1` regression that motivated this gate.
+- Pre-existing Overall-Code findings on untouched files do **not** fail an unrelated PR. To make
+  the gate enforce Overall Code as well, add Overall conditions to the gate in the SonarCloud
+  project settings (Quality Gates UI) — that is a SonarCloud-side configuration, not a repo file.
+
+When triaging a red gate, confirm via the PR analysis whether the failing condition is a **New
+Code** condition (caused by this PR — fix it) or an **Overall** condition (pre-existing — handle
+per the table below, and do not let it silently block an unrelated change).
+
+## Step A / Step B: fetch the hotspots and read each one's disposition
+
+```bash
+pnpm josh sonar:hotspots <PR>   # alias: josh shs
+```
+
+The command fetches the hotspots on the pull request from SonarCloud's public API (no auth), reading
+the project key from `sonar-project.properties`, and prints per hotspot its `status`, `component`,
+`line`, `ruleKey` and the Step B branch it falls into. The one branch key that used to be walked by
+eye — "is this path upstream-synced?" — is answered by calling `josh sync:scope`'s own detection, so
+no distribution path list is duplicated. The four branches:
+
+| Branch     | Meaning                                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `excluded` | A `TO_REVIEW` hotspot on an upstream-synced file — add the path to `sonar.exclusions`, never edit the file |
+| `local`    | A `TO_REVIEW` hotspot on project-local code — a targeted `sonar.issue.ignore.*` rule or NOSONAR comment    |
+| `fix`      | A reviewed-and-fixed hotspot — the real issue was fixed                                                    |
+| `defer`    | A reviewed hotspot set aside — out of scope for this PR                                                    |
+
+A read that failed (rate-limit, network) prints `unreadable: <reason>`, told apart from a success
+that found no hotspots. `pnpm josh oracle:list` carries the same vocabulary. **The only judgement
+left to you is whether a `TO_REVIEW` hotspot is really a false positive** — if it is, apply its
+`excluded` / `local` branch; if it is instead a real issue fix the code and add a regression test,
+and if it is out of scope mention it in the completion comment and open a follow-up Issue.
+
+## Step C: optional — mark SAFE via API if a token is available
+
+If `SONAR_TOKEN` is exported (SonarCloud user token with write scope):
+
+```bash
+curl -sS -u "$SONAR_TOKEN:" -X POST \
+  "https://sonarcloud.io/api/hotspots/change_status" \
+  -d "hotspot=<hotspot-key>&status=REVIEWED&resolution=SAFE&comment=<reason>"
+```
+
+Without a token, prefer Step B's config-based approach — that change is reviewable in the PR diff, whereas API-side state changes are not.
+
+## Reporting rules
+
+- List every outstanding hotspot in the completion comment (never hide a failing SonarCloud analysis).
+- State which action you took (excluded / marked SAFE / fixed / deferred) and why.
+- If you deferred, include a link to the follow-up Issue.

package/prompts/testing-guide.md

@@ -0,0 +1,277 @@
+# Test Generation Guide
+
+## 0. Per-Requirement Test Coverage (MANDATORY)
+
+Before writing any implementation code, **list every requirement from the user's request and assign a test to each one**. This step is non-negotiable.
+
+### Planning template
+
+For a user request with N requirements, enumerate each one before touching any source files:
+
+```text
+Req 1: "Label chip shown immediately"
+  → E2E: open editor, type new label, press Enter → chip visible without blurring
+
+Req 2: "Down arrow moves to next row"
+  → E2E: open editor on row 1, press ↓ → row 2 enters edit mode
+
+Req N: ...
+  → Unit/E2E: ...
+```
+
+### Rules
+
+- **Every user-facing behavior change** (UI interaction, keyboard shortcut, visible state change) must have a corresponding E2E test.
+- **Every logic/utility change** (pure functions, filters, transforms) must have a unit test.
+- If a test is genuinely infeasible (e.g., native OS date-picker popup cannot be driven by Playwright), write a comment in the test file explaining why and test the closest observable behavior instead (e.g., that the editor remains open after the `change` event fires).
+- Do **not** report a requirement as done if its test is missing.
+
+### Verification checklist (add to the completion gate)
+
+- [ ] Count requirements in the user's request.
+- [ ] Count tests added/updated for those requirements.
+- [ ] The two counts match (or each gap is documented as infeasible with a comment).
+- [ ] **UI changes only:** a screenshot of the affected screen was captured and visually confirmed before reporting completion (passing tests are not proof the UI looks correct — see the **UI verification (screenshot)** rule in the completion gate). If a screenshot is impossible in this environment, that is stated and the user is asked to verify visually.
+
+---
+
+## 1. Test Type Selection
+
+| Condition                                                         | Type                      |
+| ----------------------------------------------------------------- | ------------------------- |
+| `src/routes/` pages, UI components with user interaction          | E2E (Playwright)          |
+| `.ts`/`.js` utilities, `src/lib/server/`, display-only components | Unit/Integration (Vitest) |
+
+**The type is decided from the path, not by asking.** A change under `src/routes/` takes E2E; every other runtime path takes Unit — a component with interaction is reached through the route that renders it, and that route is under `src/routes/`. `pnpm josh test:declared` prints the type each untested runtime file calls for on its `required` detail line, so the choice never becomes a stop.
+
+### Test file naming & placement (one unambiguous rule)
+
+There is exactly **one** convention for every test file — never choose between two. The rules below are mandatory; some are config-enforced (a violating file runs under the wrong vitest project or not at all), others are enforced by convention/review — each rule states which.
+
+| Test kind           | Required filename        | Routed to                        |
+| ------------------- | ------------------------ | -------------------------------- |
+| Unit / integration  | `*.test.ts`              | node/unit vitest project         |
+| Component / browser | `*.svelte.test.ts`       | browser/component vitest project |
+| E2E                 | `src/routes/**/*.e2e.ts` | Playwright                       |
+
+- **Use `*.test.ts` — never `*.spec.ts`.** The `.spec.ts` suffix is forbidden for unit/integration tests. This is **lint-enforced**: the test-filename rule building blocks (`eslint/rules/test-filename.js`) are wired into `eslint/base.js` itself, so every project built on `create_base_config` — kit included, since joshuafolkken/kit#1233 — flags any `*.spec.*` file, and any file under a top-level `tests/` directory, and fails `josh lint`. **Both bans cover every JS/TS extension** — `.ts` `.tsx` `.mts` `.cts` `.js` `.jsx` `.mjs` `.cjs` — since joshuafolkken/kit#1414; `.svelte` is deliberately outside them, because the base config has no Svelte parser and a `tests/Foo.svelte` would report a parse error instead of the move instruction. A config that does not use the base can still import the blocks alone, as `@joshuafolkken/kit/eslint/test-filename` — but **wire them through `extend_restricted_syntax(<your own rules>, SPEC_FILENAME_ENTRY)`**, because flat config replaces `no-restricted-syntax` rather than merging it, so the ready-made `spec_filename_rules` / `centralized_tests_directory_rules` records drop whatever selectors that config already restricted, on exactly the files the ban applies to (joshuafolkken/kit#1414). (A vitest `{test,spec}` matcher would still accept both, but the lint rule fails loudly before a stray `.spec.ts` can drift in.)
+- **The `.svelte.` infix is required for component/browser tests and must be preserved.** `*.svelte.test.ts` routes the file to the **browser/component** vitest project (`include: src/**/*.svelte.{test,spec}.{js,ts}`); plain `*.test.ts` routes to the **node/unit** project (`include: src/**/*.{test,spec}.{js,ts}`). Renaming `Foo.svelte.test.ts` → `Foo.test.ts` silently moves it to the wrong project — do not drop the `.svelte.` infix.
+- **Colocate every test next to the code it exercises.** A top-level `tests/` directory is **not used** — place `foo.test.ts` beside `foo.ts`, and E2E specs under the relevant `src/routes/**` path. The top-level `tests/` ban is **lint-enforced** by the same rule (`eslint/rules/test-filename.js`). Note: `playwright.config.ts` discovers E2E via `testMatch: '**/*.e2e.{ts,js}'`, so an `*.e2e.ts` placed outside `src/routes/**` would still run — that specific `src/routes/**` placement is enforced by **convention/review, not config**, and must be upheld manually.
+
+> **Enforcement:** the `*.spec.ts` ban and the top-level `tests/` ban are enforced by the test-filename rule (`eslint/rules/test-filename.js`), wired into the shared `eslint/base.js`, so they fail loudly in `josh lint` for kit itself, for every consumer of that base config, and for every AI tool. Left as an export a consumer had to remember to wire in, the ban reached only the projects that did — and never the repository distributing it (joshuafolkken/kit#1233). This was chosen over tightening the vitest `{test,spec}` matchers to `{test}` only, because matcher-tightening causes **silent non-execution** of stray `*.spec.ts` files whereas a lint rule fails loudly. (Doc-only guidance had already failed to prevent this drift twice.)
+
+---
+
+## 2. Test Guidelines
+
+### Naming
+
+- Variables/functions: `snake_case` | Constants: `UPPER_SNAKE_CASE`
+- Boolean prefix: `is_`, `has_`, `should_`, `can_`, `will_`, `did_`
+
+### Test Functions
+
+- Outside `describe`: `test`; inside `describe`: `it`
+- Use `describe` only when grouping multiple tests is necessary
+
+### Parameterized Tests
+
+- Playwright: `for` loop; Vitest: `test.each` / `it.each`
+- Test cases: define as `cases` or `*_cases` array at file top (outside test functions)
+
+### Constants
+
+- All magic numbers/strings except `0`, `1`, `-1` must be `UPPER_SNAKE_CASE` constants
+- Place after imports at file top
+
+### Imports
+
+- Always include `.js` extension: `import { foo } from './bar.js'`
+- Type imports: `import { type Foo } from '...'`
+
+### Playwright
+
+- Element selection: `page.getByTestId('id')` — add `data-testid` to implementation files
+- Test functions always `async`
+- **Project split:** `playwright.config.ts` defines **`e2e-guest`** (no auth: `src/routes/**/dash-guest.e2e.ts`, `src/routes/**/demo.e2e.ts`), then **`e2e-main`** (depends on `e2e-guest`), then **`e2e-leak-check`** (depends on `e2e-main`). Authenticated projects set `storageState` to `src/routes/.auth/user.json` when that file exists — **there is no UI login on every test**; cookies/session are restored from disk.
+- **Workers:** Playwright uses `workers: 1` because authenticated E2E shares one storage state; higher parallelism races on the same DB user.
+- **Timeouts:** Guest/main/leak projects use **per-project test timeouts** in `playwright.config.ts` so switching tabs and dash actions are not cut off by the global default.
+
+### Regression fix workflow (E2E data / cleanup bugs)
+
+When fixing bugs where tests leave data behind (or similar persistent state):
+
+1. **Add or extend a failing guard** — e.g. `src/routes/dash/dash-leak-check.e2e.ts` exports `dash_leak_guard.scrub_then_assert_clean`: it scrubs tasks whose titles contain the `E2E_` automation prefix, then asserts none remain. Confirm it **fails** while scrub or per-test teardown is broken (red).
+2. **Fix production code or test teardown** — cleanup must be reliable (prefer `data-testid` over locale-specific `aria-label` for automation; avoid swallowing cleanup errors unless explicitly intended).
+3. **Confirm the guard passes** (green) with full `pnpm test:e2e` (or targeted Playwright command above).
+4. **Document** any new invariant in this guide or the relevant E2E helper module.
+
+### Error Messages
+
+- Include expected and actual values explicitly
+- Wrap `number` in template literals with `String()`
+- Don't add `?? ''` unless the value can genuinely be `undefined`
+
+### Type Safety
+
+- No `any`; always use loop variables (avoids unused-variable lint errors)
+- Use `@ts-expect-error`, not `@ts-ignore`
+
+### Statement Limit
+
+- Max 10 statements per test function; split complex tests if exceeded
+
+### No live network
+
+- **A unit test must not reach the network.** Mock every read that leaves the process — a `gh` call, an HTTP request, a CLI subprocess that makes one
+- **Mock the whole read, not the first half of it.** A helper that stubs one call and leaves a second one on its default calls through, and the test still **passes** — slower, and against whatever the remote answers. That is how joshuafolkken/kit#1353 reached a 10-second timeout in CI on a change that had nothing to do with it
+- In kit's own checkout `vitest.config.ts` arms a guard that fails the run and lists the `gh` invocations it recorded — the commands, not the test that made them, which the command text is usually enough to find (`docs/josh-commands.md` → `josh test:unit`). Elsewhere the rule holds without one
+
+### A josh command that writes state runs through the integration harness (kit only)
+
+- **A new or changed state-writing josh command needs a test in all three environments of `scripts/test/josh-harness.ts`** — kit, a consumer without `docs/`, a lane worktree (joshuafolkken/kit#2402). Packed suite: `vitest.harness.config.ts`
+
+---
+
+## 3. Checklist
+
+- [ ] **Before “done”:** **Completion gate** in `CLAUDE.md` — `pnpm josh gate` (lint, type check, spell check and unit tests), then E2E per § 6 below: the CI E2E job where a pull request is open, **`pnpm josh test:e2e`** run by you where there is none. **Do not** stop at `pnpm josh test:unit` when E2E applies, and **never** ask the user to run it. Run it with `CI` unset so Playwright uses **DEV** (`pnpm run dev` on the port `playwright.config.ts` resolves from `PORT_SEED`), matching the VS Code Test plugin. ReadLints **0 errors** on touched files; Playwright **no failures and no flaky** runs in what you report. **If Playwright cannot run in your environment:** do **not** use `pnpm build` or `CI=true` unless the user asked — say the E2E result is missing and that the gate is therefore not closed
+- [ ] Magic numbers/strings → constants (except `0`, `1`, `-1`)
+- [ ] `.js` on all import paths
+- [ ] Playwright: `data-testid` selectors only
+- [ ] `async`/`await` used correctly
+- [ ] No `any`; all loop variables used
+- [ ] Max 10 statements per test function
+- [ ] `read_lints` run; 0 errors before reporting done
+- [ ] No unnecessary `?? ''`; `String()` for numbers in template literals
+
+---
+
+## 4. Reference Files
+
+**E2E:** `src/routes/**/page.e2e.ts`, `src/routes/**/praise.e2e.ts`
+**Unit:** `src/lib/data/phrases/phrases.test.ts`, `src/lib/data/praise-audio.test.ts`
+**ESLint:** `eslint.config.js`
+
+---
+
+## 5. Unit Test Example — Stateful Functions
+
+```typescript
+import { expect, test } from 'vitest'
+import { get_praise_audio_file, reset_praise_audio_index } from './praise-audio.js'
+
+test('returns expected values in sequence', () => {
+	reset_praise_audio_index() // reset state at the start of each test
+
+	const first_result = get_praise_audio_file()
+	expect(first_result).toBe('expected-value-1')
+
+	const second_result = get_praise_audio_file()
+	expect(second_result).toBe('expected-value-2')
+})
+```
+
+---
+
+## 6. Closing the E2E gate without a human run
+
+The completion gate used to end by asking the user to run `pnpm josh test` and paste the output.
+That step is gone (joshuafolkken/kit#902). It is the rule below that replaces it, and the
+replacement is **not** a relaxation — nothing that a red local run stopped is allowed through.
+
+### Why it existed, and why it no longer does
+
+The reason was never that a human reads E2E output better. It was that `followup` waited 180
+seconds for CI, which no suite containing E2E can finish in — so the command exited red beside a CI
+that was still running, and the only reliable E2E signal left was a person's terminal. That budget
+is now derived from the distributed `templates/workflows/ci.yml` rather than picked as a round
+number: 1920 seconds, the longest run its `needs` graph permits plus runner-queue headroom, with a
+unit test that fails if a declared job budget outgrows it (joshuafolkken/kit#851). CI can now be
+waited on, so it can be relied on.
+
+### Which result closes the gate
+
+Decided by whether a pull request is open, never by judgement:
+
+| Situation                                                                                    | What closes the gate                                                                                             |
+| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| A pull request is open — `fullrun`, `backlogrun`                                             | The CI E2E job. `pnpm josh followup` waits for the checks and refuses to merge while any of them is non-passing. |
+| No pull request — `halfrun`'s stop before commit, a completion reported outside any workflow | `pnpm josh test:e2e`, run by **you**, output read by you.                                                        |
+
+**Never ask the user to run it, in either row.** A completion report is not allowed to depend on
+somebody being at the keyboard; that dependency is what made a `fullrun` chain stall at its last
+step. And never report completion on an E2E result nobody read — an unread result is not a pass.
+
+**Where the application layer ships an integrated gate, prefer it** over a bare `pnpm josh test:e2e`
+for the second row: `@joshuafolkken/app-kit` ships `pnpm josh-app verify`, which builds once and
+boots once to run the E2E suite and the DAST scan against that one server — and which delegates E2E
+to `josh test:e2e`, so the skip below still applies. **Decide by the command list the installed
+toolkit prints, not by which toolkit is installed and not by a version number written here**: the
+same rule the UI gate uses, and the only one that survives a release.
+
+### A project with no E2E suite
+
+`pnpm josh test:e2e` runs through `scripts/test/test-e2e-guard.ts`, which **skips and exits 0**, naming
+the reason, when `@playwright/test` is not installed or no `*.e2e.{ts,js}` file exists. That skip is
+a **defined** outcome, not an accident: a project with no E2E suite has nothing for the gate to
+read, and the run says so out loud. **A skip you did not see printed is not one** — it is an unread
+result, and it falls under the previous paragraph.
+
+**CI decides the same question, and now by the same rule.** The `e2e-detect` job in
+`templates/workflows/ci.yml` enables the `e2e` job when any `*.e2e.{ts,js}` exists outside
+`node_modules` — the guard's own glob, dot-directories left out the way the guard's default leaves
+them out — and it does not look at the config's filename at all (joshuafolkken/kit#991). Before
+that it required a file named exactly `playwright.config.ts` **and** an `*.e2e.{ts,js}` under `tests` or
+`src/routes`, so a suite kept anywhere else, or a config named `playwright.config.js`, read as
+"no E2E" in CI while `josh test:e2e` ran it locally: the job's `if:` went false, GitHub recorded it
+as `skipped`, the rollup parser counted the skip as passing exactly as it does for every other
+conditional job, and the first row of the table above closed the gate on a suite nobody ran.
+**Where the specs live was a precondition on the CI signal; it is now a property of the workflow.**
+The agreement is executed rather than described — `scripts/ci/ci-yml-e2e-detect.test.ts` runs the
+workflow's own script against each layout and compares its verdict to the guard's, and asserts over
+the whole matrix that no layout containing specs can yield `enabled=false`. § 1's placement
+convention still stands on its own merits (`eslint/rules/test-filename.js` bans a top-level
+`tests/` directory outright), but the CI signal no longer depends on following it.
+
+**One difference from the guard remains, and it is deliberate and one-sided.** The guard also skips
+when `@playwright/test` is not installed, which is what keeps that optional peer optional for the
+pre-push hook; CI enables the job on the spec alone, so a spec that cannot run ends red rather than
+silently green. Enabling more than the guard costs a failed job, enabling less costs a merge — so
+the difference may widen in that direction and never narrow.
+
+### The gate is not weakened
+
+Two properties carry the verification the human step used to carry, and both are asserted by tests
+rather than left to prose:
+
+- **A non-passing check keeps the merge closed.** `evaluate_pr_state` returns `success` only when
+  GitHub reports the pull request `CLEAN` **and** every required check passes. A failing E2E job
+  makes GitHub report `UNSTABLE`, and the one opening in that wall — `is_unstable_only_from_coderabbit`,
+  the temporary kit#753 policy — applies only when _every_ non-passing check is CodeRabbit's. So a
+  red E2E can never reach `success`, and `followup` exits non-zero instead of merging.
+- **Weakening the gate is a workaround, and the workaround rules apply to it.** Filtering,
+  narrowing or reinterpreting E2E output to get past it is the violation `CLAUDE.md` names under
+  "Cross-package problems"; reporting the filtered result honestly does not make it compliant.
+
+**`E2E` stays off the required-check list, and that is a decision rather than an oversight**
+(joshuafolkken/kit#991). A required check is satisfied by a _skipped_ job — the rollup parser maps
+`SKIPPED` to `pass` — so requiring `E2E` would have passed on exactly the skipped job described
+above, which is the failure it looks like it would have caught. It adds nothing to the failure path
+either: a red E2E already ends the wait on the poll that sees it. What it would add is a cost —
+a repository whose CI reports no `E2E` context at all resolves the required entry to `missing`,
+which is never `pass`, so the evaluation stays `pending` until the 32-minute wait times out with
+nothing actually wrong. What guarantees the job runs is the detection rule above, not the required
+list. A project that wants it required opts in through `JOSH_REQUIRED_CHECKS`, which
+`scripts/git/git-pr-checks-eval.test.ts` covers; the decision itself — `E2E` off the default list,
+and a repository reporting no `E2E` check still mergeable — is pinned in
+`scripts/git/git-pr-checks-e2e-gate.test.ts`.
+
+**A red E2E is reported as soon as it goes red, and by name.** `E2E` is not on the required list, so
+until joshuafolkken/kit#990 nothing ended the wait when it failed: the rollup read as pending,
+`followup` ran out its 32-minute budget, and the run ended in `Timed out while waiting for PR checks
+to complete.` — a message naming neither the job nor the cause. Any failing check now ends the wait
+on the poll that sees it, and the error names it (`PR checks failed (failed checks: E2E).`).
+The poll loop keeps CodeRabbit exempt under the temporary kit#753 policy. **This is a change to how fast the gate
+reports, never to what it lets through** — no failing check gained a path to `success`, which
+`scripts/git/git-pr-checks-e2e-gate.test.ts` continues to assert.