Coverage

Scope. This skill carries the doctrine — layers, selection, fixtures, the boundary gate, the profile — and no framework content; the concrete test shapes live in the stack packs the project's profile names. Precision against audit is the Not for clause.

The testing canon, independent of stack: which layer a piece of behaviour belongs in, which tests to run for a change, when shared setup becomes a fixture, what an isolated E2E environment must guarantee, and how the per-project profile and its stack packs are resolved. What a test looks like in a given framework is not here: the project's .context/profiles/testing.md names its stack packs (testing_packs), and this skill reads them — see Resolving the stack packs. Per-project facts (ports, database names, commands, personas) live in that profile, never here — see references/14-testing-profile.md.

The full suite is a boundary gate, not a phase gate. Per change, run the narrowest selection that can observe it (/aidex:audit affected-tests --command, or the profile's single-test command, or one spec via ./test-e2e.sh e2e/<spec>.spec.ts); the whole suite runs once, at plan close-out or pre-merge. A full E2E suite costs ~5 minutes; spending that per change is what this rule exists to stop.

A test that execs a script that can hang runs it bounded — own process group killed on timeout, plus an inherited CPU cap — never a bare timeout=, which orphans the grandchildren. The rule and its incident live in ${CLAUDE_PLUGIN_ROOT}/skills/bugfix/SKILL.md step 3.

Writing a test is testing's. The four questions asked before a test is added, the one-owner rule and the patterns of a test that earns nothing live in ${CLAUDE_PLUGIN_ROOT}/skills/testing/SKILL.md; this skill is the doctrine it points to.

What this skill is not. It does not run an audit, does not build or read module-map.json or coverage-matrix.json, does not track a finding through its lifecycle, and does not carry the suite-speed measurement procedure. All of that is audit's test-coverage playbook (skills/audit/assets/templates/methodology/test-coverage.md.template). The split is by type, not by overlap: this skill owns the reference corpus and authoring rules — including the per-module judgment-pass checklist (references/06-judgment-pass.md) that the playbook's judged layer runs; the playbook owns inventory, finding lifecycle, matrix, sweep and escalation, and is the one that executes that checklist. The one rule with a foot in both — "a coverage percentage without a declared denominator is not a measurement" (m7) — is not duplicated: the playbook runs it as an inventory-time check ("is the denominator declared? can coverage even run?"), this skill states it as an authoring rule for anyone writing a new coverage-bearing test.

When to read what

This is the only table of references; references/00-index.md records which plan phase produced each file.

Resolving the stack packs

1. Read <project>/.context/profiles/testing.md. If it does not exist, seed it: python3 ${CLAUDE_PLUGIN_ROOT}/skills/coverage/scripts/profile-init.py <project> (never --force over an existing one; blank keys are unanswered, not zero).
2. Take testing_packs — a space-separated list of skill names — and read each pack's ~/.claude/skills/<pack>/SKILL.md; its "Question -> file" table says which of its references answers the question at hand. Read with Read; a pack is never invoked as a skill (disable-model-invocation: true), so nothing fires on its own.
3. Apply the doctrine here first — layer, selection, gate — then the pack's shape. When the two disagree, the doctrine wins and the disagreement is a project decision, not a profile line.
4. testing_packs blank or naming a pack that is not installed: say so and name the missing pack; do not improvise the framework content from memory, and do not add it to this skill. A stack with no pack gets a new testing-<framework> pack in myskills (the shape is in references/14-testing-profile.md).

The full pack table is in references/14-testing-profile.md.

What the generated test-e2e.sh guarantees

The Playwright packs generate the script; this is the contract their template is tested against (testing-playwright-app/tests/test-gen-test-e2e.sh asserts each line):

• It targets a disposable database cloned from a template, never dev's, and never ships a dev-port Playwright config.
• It sources the checkout's .env before its port defaults apply and exports E2E_DB_PORT, so an worktree checkout drives its own stack; it never sets COMPOSE_PROJECT_NAME (the worktree owns it).
• It reclaims the image layer its run orphans: every rebuild inside the run leaves the previous image untagged but still labelled with the compose project, so the ids tagged before the run that are dangling after it are removed by exact id (never prune, never volumes); a failed build moves no tag and removes nothing. Proven against a real daemon by tests/test-layer-reclaim.sh. Background: aidex BL-372/BL-377, the 289 layers that filled Docker's virtual disk on 2026-09-08.

The shape of the docs this skill writes

This skill writes into two places in a project, and each has one shape (reference/references/03-shaping.md is the canon; this is its application):

• No rule is stated in two files. The index says which module owns it; the others link. Two modules restating the same rule drift apart and end up contradicting each other, and the reader has no way to tell which copy is current.
• A doc this skill extends past ~2,500 words is split into a new module, never appended. The tripwire asks "is there a second workflow in here?"; the answer for a cross-dependency map that gains execution groups is yes, so the groups get their own NN-execution-groups.md and the index a new row.
• cross_deps_ref may name a folder or several modules, not one file — a single named file is where every later workflow gets appended until it is a monolith.
• python3 ${CLAUDE_PLUGIN_ROOT}/skills/coverage/scripts/profile-init.py --check <project> is the tripwire in script form: it warns on a prose section in the profile and on any references/testing/*.md over 2,500 words. Run it at the close of any phase that touched either.

How to use the layer model

1. Read references/01-layer-model.md's six layers and the assignment rubric.
2. Apply the rubric's maxim: test the decision, not the pixels — except when the browser is what decides. If the correctness question is "did the right thing happen" (a total computed, a row persisted, a permission enforced), it belongs at the lowest layer that can observe that. If the correctness question is "did the browser render, lay out, or navigate correctly" — CSS-dependent behaviour, focus order, a router transition — or "does the real frontend + backend + database integration hold", which a mock cannot vouch for, no layer below E2E can answer it, so that is where it belongs.
3. State the layer and the one-sentence reason when proposing where a new test goes; do not silently default to E2E because it is the layer that can see everything — that is exactly the over-assignment the rubric exists to prevent.

How to use the best-practices corpus

references/02-best-practices.md holds the stack-independent entries: item 5 quotes a fetched primary source with its check date, item 1 records the sweep itself, item 4 is flagged unverified, items 7 and 8 point to 01-layer-model.md, and items 2, 3 and 6 are stubs pointing at the stack pack that now carries them (a framework trap lives with its framework). Do not extend this file by transcribing anything from a chat, a consultation artifact, or a session transcript. A new item is only added once its primary source has been fetched and quoted, with a version and a date attached — that constraint is the reason this file exists rather than a copy of an unverifiable draft. Items marked unverified are flagged as such deliberately and must not be promoted to a stated fact without re-checking the source.

How to use the fixtures convention

references/03-fixtures-convention.md states the rule-of-three trigger (extract to __fixtures__/ at the third test repeating the same setup), the authoring form of m7, and the __tests__/ layout ratchet (s4): a test file moves to __tests__/ when the code it covers is touched, never as a scheduled mass move. All three are mechanical, not a judgment call — apply them while writing or moving tests, not only when reviewing them later.

How to use the E2E layer audit

references/04-e2e-layer-audit.md is the template: scope discipline, row format, and how a verdict is argued against the rubric above — E2E (stays) or candidate (a lower layer could observe the same failure). A completed table is project data and lives in that project's own .context/, never in this skill. It is an audit, not a queue — a candidate verdict names the reason and the likely lower layer; deciding to move a spec, and moving it, is separate work.

How to use diff-cover

references/05-diff-cover.md documents the on-demand changed-lines coverage check: the exact host-run command, the recorded threshold and its ADR, and why it is never a hook or CI gate (q4). Point someone here when a gap finding is being closed with new tests, or when asked "did the branch I just wrote test its own changes" — never propose wiring this into a hook or pipeline; the reference states why not.