feat: per-file coverage delta reporting, Codecov banners, and agent test requirements

.github/workflows/unit-tests.yml

@@ -32,4 +32,7 @@ jobs:
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5.5.4
         with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          flags: unit
+          verbose: true
           fail_ci_if_error: false

AGENTS.md

@@ -69,9 +69,10 @@ When updating data, change **all three** together so they stay consistent.
 ## Running Tests
 
 ```bash
-npm ci            # install devDependencies
-npm test          # jest --coverage (interactive)
-npm run test:ci   # jest --ci --coverage (CI mode; fails on coverage drop)
+npm ci                # install devDependencies
+npm test              # jest --coverage (interactive)
+npm run test:ci       # jest --ci --coverage (CI mode; fails on coverage drop)
+npm run test:e2e      # Playwright E2E tests (requires a local static server — auto-started by config)
 ```
 
 **Coverage thresholds** (enforced in CI):
@@ -84,6 +85,20 @@ npm run test:ci   # jest --ci --coverage (CI mode; fails on coverage drop)
 
 The current measured coverage is ≈ 96 % statements / 88 % branches — do not let it drop below the thresholds.
 
+### Agent testing requirements
+
+Every time an agent makes changes to this repository it **must**:
+
+1. Run `npm run test:ci` and confirm all unit tests pass before finishing.
+2. Run `npm run test:e2e` and confirm all E2E tests pass before finishing.
+3. Ensure coverage does **not** decrease — the Codecov status check enforces this on PRs (any negative delta fails the check).
+
+When adding or modifying code, agents **must** write matching tests:
+
+- **Pure functions in `death-clock-core.js`** → add/update unit tests in `tests/death-clock.test.js`. Aim to keep coverage at or above current levels; do not let it drop.
+- **DOM behaviour or visual flows in `script.js` / `index.html`** → add/update E2E assertions in `tests/e2e/death-clock.spec.js` where practical.
+- Do not write tests purely for the sake of coverage numbers. Every test must assert real, meaningful behaviour that would catch a regression if the code broke.
+
 ---
 
 ## Making Changes
@@ -167,5 +182,7 @@ uses: actions/checkout@v6
 - Do **not** skip tests when adding new pure functions to the core module.
 - Do **not** change `BASE_TOKENS` / `TOKENS_PER_SECOND` / `BASE_DATE_ISO` independently — update all three as a set with a comment explaining the source.
 - Do **not** use mutable tags (e.g. `@v6`) in `uses:` — always pin to a commit SHA with a full semver comment (e.g. `@abc1234... # v6.0.2`).
+- Do **not** finish a session without running `npm run test:ci` and `npm run test:e2e` to confirm both suites pass.
+- Do **not** let coverage decrease — a negative coverage delta on any PR fails the Codecov status check.
 - Do **not** edit `changelog-data.js` or `milestones-data.js` directly — they are auto-generated; edit `CHANGELOG.md` / `milestones.yaml` and run the corresponding build script.
 - Do **not** bump the version in `package.json` manually — let release-please handle it via Conventional Commits.

README.md

@@ -51,6 +51,18 @@ Tests are in `tests/death-clock.test.js` and cover all pure functions in `death-
 
 ---
 
+## Coverage
+
+Unit-test coverage is tracked by [Codecov](https://codecov.io/gh/nitrocode/token-deathclock). Every pull request receives an automated comment showing per-file coverage deltas; the PR check fails if coverage decreases.
+
+| Unit test coverage | Coverage breakdown |
+|---|---|
+| [![Codecov icicle](https://codecov.io/gh/nitrocode/token-deathclock/branch/main/graphs/icicle.svg)](https://codecov.io/gh/nitrocode/token-deathclock) | [![Codecov sunburst](https://codecov.io/gh/nitrocode/token-deathclock/branch/main/graphs/sunburst.svg)](https://codecov.io/gh/nitrocode/token-deathclock) |
+
+E2E tests run in CI via Playwright (Chromium). Their pass/fail status is shown by the **E2E Tests** badge above.
+
+---
+
 ## Deployment (GitHub Pages)
 
 The site is automatically deployed on every push to `main` via the `deploy.yml` workflow.

codecov.yml

@@ -0,0 +1,24 @@
+# Codecov configuration
+# https://docs.codecov.com/docs/codecov-yaml
+
+coverage:
+  status:
+    # Fails the PR check if the overall project coverage decreases at all.
+    project:
+      default:
+        target: auto       # compare against the base commit
+        threshold: 0%      # zero tolerance — any drop in project coverage fails
+    # Fails the PR check if lines changed in the PR are not covered.
+    patch:
+      default:
+        target: auto
+        threshold: 0%      # lines touched in the PR must not reduce coverage
+
+comment:
+  # Show per-file coverage deltas in every PR comment.
+  layout: "reach, diff, flags, files, footer"
+  behavior: default        # post a new comment; update on subsequent pushes
+  require_changes: false   # always post, even when no coverage changes
+  require_base: false
+  require_head: true
+  show_carryforward_flags: false