From da410e9d7f3ed2fd0954807e3623e84263c69930 Mon Sep 17 00:00:00 2001
From: Steven Enamakel <31011319+senamakel@users.noreply.github.com>
Date: Sat, 2 May 2026 14:53:35 -0700
Subject: [PATCH] docs: surface 80% coverage gate and scripts/debug runners
 (#1108)

---
 .github/ISSUE_TEMPLATE/bug.md     |  1 +
 .github/ISSUE_TEMPLATE/feature.md |  1 +
 .github/PULL_REQUEST_TEMPLATE.md  |  1 +
 .github/workflows/coverage.yml    |  6 ++++++
 AGENTS.md                         | 32 +++++++++++++++++++++++++++++++
 CLAUDE.md                         | 32 +++++++++++++++++++++++++++++++
 6 files changed, 73 insertions(+)

diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md
index 85c720929..757d175a9 100644
--- a/.github/ISSUE_TEMPLATE/bug.md
+++ b/.github/ISSUE_TEMPLATE/bug.md
@@ -23,6 +23,7 @@ Suspected cause, workaround, or proposed fix. Skip if unknown.
 
 - [ ] **Repro gone** — Bug no longer reproduces on the stated environment (or root cause documented if intentional).
 - [ ] **Regression safety** — Unit, integration, or E2E coverage added or updated if this should not come back.
+- [ ] **Diff coverage ≥ 80%** — the fix PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml)).
 - [ ] **…** — Other verify-before-close items.
 
 ## Related
diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md
index c9732c413..749c23e37 100644
--- a/.github/ISSUE_TEMPLATE/feature.md
+++ b/.github/ISSUE_TEMPLATE/feature.md
@@ -24,6 +24,7 @@ How you plan to solve it — scope (core / app / both), approach, tradeoffs. Ski
 - [ ] **Feature 1** — TODO
 - [ ] **Feature 2** — TODO
 - [ ] **Feature 3** — TODO
+- [ ] **Diff coverage ≥ 80%** — the implementing PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by [`.github/workflows/coverage.yml`](../../.github/workflows/coverage.yml)).
 
 - …
 
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 7d9e56875..f2c1c4c86 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -18,6 +18,7 @@
 > If a section does not apply to this change, mark the item as `N/A` with a one-line reason. Do not delete items.
 
 - [ ] Tests added or updated (happy path + at least one failure / edge case) per [`docs/TESTING-STRATEGY.md`](../docs/TESTING-STRATEGY.md#failure-path-requirement)
+- [ ] **Diff coverage ≥ 80%** — changed lines (Vitest + cargo-llvm-cov merged via `diff-cover`) meet the gate enforced by [`.github/workflows/coverage.yml`](../.github/workflows/coverage.yml). Run `pnpm test:coverage` and `pnpm test:rust` locally; PRs below 80% on changed lines will not merge.
 - [ ] Coverage matrix updated — added/removed/renamed feature rows in [`docs/TEST-COVERAGE-MATRIX.md`](../docs/TEST-COVERAGE-MATRIX.md) reflect this change (or `N/A: behaviour-only change`)
 - [ ] All affected feature IDs from the matrix are listed in the PR description under `## Related`
 - [ ] No new external network dependencies introduced (mock backend used per [`docs/TESTING-STRATEGY.md`](../docs/TESTING-STRATEGY.md#mock-policy))
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 0a86243be..895b9eb50 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -12,6 +12,12 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.head_ref || github.ref }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    # The CI container's default `sh` is dash, which rejects `set -o pipefail`
+    # and bashisms like `mapfile`. Force bash for every `run:` step.
+    shell: bash
+
 jobs:
   frontend-coverage:
     name: Frontend Coverage (Vitest)
diff --git a/AGENTS.md b/AGENTS.md
index 17838e671..2e6655673 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -73,6 +73,38 @@ cargo check --manifest-path app/src-tauri/Cargo.toml
 
 **Quality**: ESLint + Prettier + Husky in the `app` workspace.
 
+### Agent debug runners (`scripts/debug/`)
+
+Use these wrappers instead of invoking Vitest / WDIO / cargo directly when iterating — they keep stdout summary-sized and tee full output to `target/debug-logs/<kind>-<suffix>-<timestamp>.log`. Add `--verbose` to also stream raw output. See [`scripts/debug/README.md`](scripts/debug/README.md).
+
+```bash
+# Vitest
+pnpm debug unit                                    # full suite
+pnpm debug unit src/components/Foo.test.tsx        # one file (positional pattern)
+pnpm debug unit -t "renders empty state"           # filter by test name
+pnpm debug unit Foo -t "renders empty" --verbose
+
+# WDIO E2E (one spec at a time)
+pnpm debug e2e test/e2e/specs/smoke.spec.ts
+pnpm debug e2e test/e2e/specs/cron-jobs-flow.spec.ts cron-jobs --verbose
+
+# cargo tests (delegates to scripts/test-rust-with-mock.sh)
+pnpm debug rust
+pnpm debug rust json_rpc_e2e
+
+# Inspect saved logs
+pnpm debug logs                  # list 50 most recent
+pnpm debug logs last             # print most recent (last 400 lines)
+pnpm debug logs unit             # most recent matching prefix "unit"
+pnpm debug logs last --tail 100
+```
+
+Files: `scripts/debug/{cli,unit,e2e,rust,logs,lib}.sh`. Entry point: `pnpm debug` (`scripts/debug/cli.sh`).
+
+### Coverage requirement (merge gate)
+
+PRs must meet **≥ 80% coverage on changed lines**. Enforced by [`.github/workflows/coverage.yml`](.github/workflows/coverage.yml) via `diff-cover` over merged Vitest + `cargo-llvm-cov` (core + Tauri shell) lcov outputs. Below the threshold the PR will not merge. Run `pnpm test:coverage` and `pnpm test:rust` locally; add tests for new/changed lines (happy path + at least one failure / edge case).
+
 ---
 
 ## Configuration
diff --git a/CLAUDE.md b/CLAUDE.md
index d01ad0a24..4a058e8d9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -54,6 +54,38 @@ cargo check --manifest-path app/src-tauri/Cargo.toml
 **Tests**: Vitest in `app/` (`pnpm test:unit`, `pnpm test:coverage`); Rust via `cargo test`.
 **Quality**: ESLint + Prettier + Husky in `app`.
 
+### Agent debug runners (`scripts/debug/`)
+
+Bounded-output wrappers around the project test runners. Stdout stays summary-sized (so it fits in agent context); full output is teed to `target/debug-logs/<kind>-<suffix>-<timestamp>.log`. Add `--verbose` to also stream raw output. Prefer these over invoking Vitest / WDIO / cargo directly when iterating.
+
+```bash
+# Vitest
+pnpm debug unit                                    # full suite
+pnpm debug unit src/components/Foo.test.tsx        # one file (positional pattern)
+pnpm debug unit -t "renders empty state"           # filter by test name
+pnpm debug unit Foo -t "renders empty" --verbose
+
+# WDIO E2E (one spec at a time)
+pnpm debug e2e test/e2e/specs/smoke.spec.ts
+pnpm debug e2e test/e2e/specs/cron-jobs-flow.spec.ts cron-jobs --verbose
+
+# cargo tests (delegates to scripts/test-rust-with-mock.sh)
+pnpm debug rust
+pnpm debug rust json_rpc_e2e
+
+# Inspect saved logs
+pnpm debug logs                  # list 50 most recent
+pnpm debug logs last             # print most recent (last 400 lines)
+pnpm debug logs unit             # most recent matching prefix "unit"
+pnpm debug logs last --tail 100
+```
+
+Files: `scripts/debug/{cli,unit,e2e,rust,logs,lib}.sh` plus `README.md`. Entry point is `pnpm debug` (`scripts/debug/cli.sh`).
+
+### Coverage requirement (merge gate)
+
+PRs must meet **≥ 80% coverage on changed lines**. Enforced by [`.github/workflows/coverage.yml`](.github/workflows/coverage.yml) using `diff-cover` over merged Vitest (`app/coverage/lcov.info`) and `cargo-llvm-cov` (core + Tauri shell) lcov outputs. Below the threshold the PR will not merge — add tests for new/changed lines, not just the happy path.
+
 ---
 
 ## Configuration