Test Coverage Loop - Measure, Triage, Fix (Deliberate)
You drive a deliberate loop that raises a project's test coverage to its requirement: run the capture, work the weak points by tier, reconcile the docs, loop until the requirement holds or the loop plateaus. Coverage lives OUTSIDE the build flows - implementers write each task's tests as part of done, but nothing in a build run measures coverage - so this loop is the user-controlled cadence where the accumulated gap gets worked. The named tradeoff of that model: a feature can land below the requirement between runs - this loop is where it catches up. The measurements behind these rules live in references/evidence.md - an audit appendix, not a run-time load.
When to use
- The deliberate coverage analyze-triage-fix loop: it runs capture-quality's coverage part, works the coverage doc's weak points by tier - structural gaps flagged for a user decision, never auto-applied - re-runs the capture to reconcile the docs, and loops until the requirement holds or the loop plateaus.
- Not for a measure-only run with no fixes (/capture-quality coverage alone), a code-quality polish (loop-code-quality), or an architecture / structure pass (loop-architecture-quality).
Modes. Mode flags right after the command - --mode-auto-run-on, --mode-auto-run-off, --mode-output-scorer-on, --mode-output-scorer-off - are switches, not the request: strip them; with only flags typed, run as with no arguments. Under the hook's auto-run contract, follow it. With no hook line (hooks off, Cursor), -on holds for this run only: each stop takes its (Recommended) option, listed in the close, an unmarked one waits, nothing goes outward, no fresh-session hand-off, and the close says auto-run ended; --mode-output-scorer-on grades this run's output like a typed stack. A typed 'no stops' or 'run it without asking me' is no waiver in this flow: say in one line that --mode-auto-run-on right after the command turns auto-run on, and never hand-write an AUTO line.
Execution modes
When dispatch is available, ask ONE question before ANALYZE and hold the answer for the run; the mark sits on the mode the habits-execution-strategy verdict picks (parallel seats moves it to the seats, listed first):
Work the fixes here (INLINE) or through the stack seats (DELEGATED)? <the verdict's reason>
- 'In this session (Recommended)' - <why it fits one chat>
- 'Dispatch the stack seats' - <the briefs that run in parallel>
No dispatch capability, or a non-stack project, is INLINE without asking. INLINE works every fix yourself in this session. DELEGATED dispatches each test-writing brief to the matching <stack>-implementer seat, exactly as the roster spells it (alfred-code:<seat> where the core plugin carries it), up to ALFRED_CODE_MAXIMUM_RUN_AGENTS at once (default 5), routes a red build/test to the matching resolver, and runs a substantial refactor through the stack's designer -> implementers -> verifier vertical (this skill's own references/domain-trio-protocol.md). In DELEGATED mode, the mode ask's answer IS the dispatch consent for small test-writing briefs: write the <data root>/state/approvals/loop-test-coverage-quality/APPROVAL stamp (APPROVED small-tier - "<the answer, verbatim>") the moment that answer lands (under auto-run the hook's AUTO stamp already stands - leave it), and rewrite it as substantial-tier plan approvals arrive - the dispatch guard is deliberately tier-blind, so an unstamped small-brief dispatch just bounces. A surface with no matching seat runs INLINE regardless. In BOTH modes the instrumented run stays the capture's, in the main session - a coverage run never enters a dispatch brief (seat gates are fast; the capture owns the measurement).
The loop
1. ANALYZE
Run capture-quality with test-coverage-quality <DELEGATED|INLINE> <scope> - this run's mode, then its scope - by INVOKING it: the Skill tool, never its protocol replayed from memory (where no Skill tool exists, say the coverage capture cannot run here and stop - a hand-rolled measurement is not comparable across rounds). A Skill call the fresh-session guard blocks is the gate working, not a fault - on 'continue', re-issue the same Skill call: the answered offer lets it through until the context grows 1.5x past it:
The fresh-session guard held the capture at <N>k; a fresh session restarts at <M>k.
- 'Resume in a fresh session (Recommended)' - this turn ends with the RESUME BLOCK
- 'Continue here' - the same Skill call again
The load is step zero of ANALYZE, not optional homework: a round that has not loaded the capture this session has not run it, whatever it measured - unloaded rounds hand-roll their own aggregation, so no two rounds' numbers are comparable, and the class-level aggregation the protocol looks past hides uncovered lines an ad-hoc dig only finds by luck. It owns the detection, the instrumented runs, and the judgment, and it writes <docs-path>/quality/COVERAGE-QUALITY.md. That doc is this loop's work list: the weak points, each carrying a tier (the routing key) and a simplify-testing action. The requirement and exclusions come from the doc; changing either is a user decision recorded there, never a loop shortcut.
2. TRIAGE + FIX by tier
Confirm the green baseline (build + tests) first - round 1 also records the sweep baseline: HEAD, or on a dirty tree the sha git stash create prints; the final anti-gaming sweep diffs against it - then take the weak points in leverage order:
small (missing tests on existing seams) - a scoped brief: the module, the uncovered symbols, the behavior each test must pin. Write them INLINE, or DELEGATED dispatch the stack's implementer with the brief - the brief states
plan: loop-test-coverage-quality(the small-brief stamp's own id) andnote: none(a scoped test brief has no note hand-off; one that does hand a note names it literally, read side included - handoff hygiene:references/domain-trio-protocol.md). Tests assert behavior - a test written to touch lines is gamed coverage, not progress.substantial (a testability refactor, or 'no test infrastructure') - designer-led with approval. 'No test infrastructure' goes FIRST when it is on the list - nothing else is measurable until a harness exists: propose the runner the stack's house testing skill records as its default (absent one, the framework's own documented default, cited), and on approval wire the runner + coverage output and land the first tests. Each substantial item runs five acts in order:
Plan it - turn the simplify-testing action into a plan; a refactor for testability is still a refactor.
Gate the plan -
task-verify-plan, an actual Skill invocation, recording itsPasses:line.Get the user's approval before building - present the plan, then (plain-text options where the harness lacks the tool):
<plan id>, <N> tasks. Build it? - 'Approve and build (Recommended)' - stamp, then fan out - 'Changes needed' - I ask what to change next, in plain textRecord the approving answer. DELEGATED: write
<data root>/state/approvals/<plan id>/APPROVAL(<plan id>is this loop's own,loop-test-coverage-quality), first lineAPPROVED <plan id> - "<the user's words, verbatim>"(under auto-run the hook'sAUTOstamp already stands - leave it) - the selected answer IS those words (the dispatch hook blocks an unstamped implementer; delete the file when the run completes). A question the idle timeout closed is no answer: its result opens 'No response after' and says the user may be away from keyboard, even when it carries an option already selected - write no APPROVED or AUTO line from it; re-ask, or stop and say what waits. Write the stamp at the ABSOLUTE path<project root>/<data root>/state/approvals/<plan id>/APPROVALwith the Write tool, and give every implementer brief the lineplan: <plan id>- the dispatch hook passes a brief only on its own plan's stamp. A relative write follows whatever cwd the shell drifted to and the dispatch then bounces. The stamp belongs to the session that dispatches - written when its own decision lands, deleted at its own close; an earlier session's leftover stamp is not consent. If BOTH the Write tool and an absolute-path Bash write are refused by the harness's classifier, stop and ask rather than retrying blind or dispatching around the gate:Both write routes refused the approval stamp: <the refusal>. - 'Retry the stamp (Recommended)' - allow the write at the prompt - 'Run this fix inline' - no dispatch, no stampBuild and gate it - INLINE yourself, DELEGATED through the domain trio.
structural - do NOT auto-apply. Present the gap, the reasoning, and the rework, then ask (plain-text options where the harness lacks the tool); declined -> flagged in the final report:
<gap> is structural: <the rework>. - 'Defer (Recommended)' - <why it can wait> - 'Apply - routes as substantial' - <what it touches> - 'Decline' - <the tradeoff kept>decline or defer adds the gap to this run's declined set - an in-context list only, never written to a file: the same gap reappearing in the next round's fresh capture is checked against it and skipped without a second ask. A fresh session starts clean and may ask again.
Keep build and tests green across the round - a red routes to the matching resolver (DELEGATED) or is fixed inline before the next weak point.
A fix that rewrites or deletes an EXISTING spec flagged red-check pending (the capture digest's suite-quality label - the spec's name promises a behavior the audit says it never guards) runs the red-check FIRST: temporarily break that behavior and run the spec.
- Still green proves the flag: fix the spec and require RED against the same break before restoring.
- Goes red means a false positive: leave the spec and report the disproof in the round outcome, so the step-3 reconcile records
red-check: disproved <date>on the entry (the doc is the capture's to write; later captures honor the recorded disproof instead of re-flagging).
The label has no other enforcement point - this step is it.
3. UPDATE DOCS
Re-run the capture: <docs-path>/quality/COVERAGE-QUALITY.md and the raw results reconcile with what landed - closed weak points drop off, the numbers refresh, anything the fixes exposed is added. The doc is regenerated by the capture, never hand-edited here. COVERAGE-QUALITY.md is the only doc this loop maintains - <docs-path>/quality/ARCHITECTURE-ASSESSMENT.md is the findings capture's, reconciled at its own cadence, never touched from here.
4. LOOP or STOP
Decide off the reconciled numbers the step-3 capture just produced, not by eye - they are already in this context (re-read <docs-path>/quality/COVERAGE-QUALITY.md only after a compaction or when the in-context picture is genuinely stale, never as a per-round habit). On a LOOP verdict, run the fresh-session ask (Bounded and honest) before the next round - the resume invocation names the rounds already consumed so the 3-round cap survives a resume. The round verdict line carries the ask's receipt - next: fresh-session | continue - "<the user's answer, verbatim>" - and that receipt can only come from the AskUserQuestion answer; a verdict line without it is an unfinished step 4:
- SATISFIED - every measured surface meets the requirement, and only user-declined structural items or recorded overrides remain.
- PLATEAU - the weak-point set equals the previous round's and none is now resolvable - stop rather than re-run identically.
- CAPPED - the improve-round cap is reached (see Bounded and honest).
- BLOCKED - only structural gaps remain and the user has not approved a rework.
On STOP, when any fix shipped: Read references/anti-gaming-sweep.md and run its four commands against the sweep baseline, after the final build + tests - a gamed bar is a BLOCKER, reverted and fixed before the report.
Then the final report - one line per field, a table for the per-surface numbers (the close is an answer like any other and the answer budget caps prose; tables are exempt): **Outcome**: <SATISFIED | PLATEAU | CAPPED | BLOCKED> on round <n> first, the line the commit gate reads as the run's end; per-surface coverage before -> after; each weak point resolved (tier + the change that closed it); the deferred items; the reconciled docs' state; the build + tests baseline at stop; Anti-gaming: <clean | what was reverted> (the sweep's verdict; n/a - no fix shipped when none did); and notes purged: <names|none>, fold-first (the trio reference's receipt, restated here because a loop round does not load that reference). When the report closes with uncommitted work and no next round queued, delete the round's APPROVED stamp first - every implementer and verifier has returned, and the checkpoint's generic security seat bounces off a live one (an AUTO stamp stays with its owner, and the checkpoint runs that half inline) - then the commit decision is the ask below, never a prose 'your call' bullet, which drifts unresolved while the uncommitted set grows. The same close names what this round's runs started and still have up - a Docker container or compose stack, seeded integration-test data, a background process - and puts tear-down-vs-keep through the same AskUserQuestion call (started-nothing is said plainly, and what the round did not start is never touched):
<N> files changed, uncommitted.
- 'Commit now (Recommended)' - `habits-commit-checkpoint`, whole
- 'Hold - review the diff first' - nothing committed
This round started <what is still up>.
- 'Tear it down (Recommended)' - only what this round started
- 'Keep it running' - named in the report
Example
INLINE, one round over a two-surface workspace:
- ANALYZE - the capture writes COVERAGE-QUALITY.md: the .NET API at 84% vs 90% (two small weak points - uncovered error branches in
InvoiceService- and one substantial:PaymentGatewaynews up itsHttpClient, untestable), the Angular app at 91% - meets. - TRIAGE + FIX - green baseline confirmed. Small: write the four branch tests, suite green. Substantial: plan the seam (inject the handler), get approval, apply + test.
- UPDATE DOCS - re-run the capture: the .NET surface reads 92%, the closed weak points drop off.
- LOOP or STOP - every surface meets the requirement -> SATISFIED; report.
Bounded and honest
Hard cap: 3 improve rounds - each round re-runs the instrumented capture; do not loop chasing the last decimal.
Each round boundary is a fresh-session resume point - the reconciled
<docs-path>/quality/COVERAGE-QUALITY.mdis the handoff; carried-forward conversation (not tool output) is what a fresh session sheds. A step, not advice: at each LOOP decision, ask - the fresh-session option ALWAYS one of its options, and when the hook refuses the ask because a fresh session does not pay back, start the next round here (its receiptnext: continue - "refused: a fresh session does not pay back"). Mark the fresh option only when a hook's fresh-session text in this session says a fresh session pays back, and then it goes first, the in-session option after it unmarked; on Claude Code the stop-contract hook drops it where one does not, and when that leaves one option it refuses the ask - then take the option it names.Round <N>: LOOP - <what is left>. A fresh session restarts from the reconciled doc at <M>k. - 'Continue here (Recommended)' - the next round in this chat - 'Resume in a fresh session' - the RESUME BLOCK, then this turn endsOn 'fresh', end the turn with this RESUME BLOCK and nothing else - the new session must be able to start from it alone, and the invocation names the rounds already consumed so the 3-round cap survives:
RESUME - loop-test-coverage-quality Invocation: /loop-test-coverage-quality <scope> - resumed round <N of 3> (rounds consumed: <list>) Sweep baseline: <sha recorded at round 1> - the final anti-gaming sweep diffs against it Read first: <docs-path>/quality/COVERAGE-QUALITY.md - its ## Resume section RANGED, never the whole file - and the requirement and exclusions it records; then the coverage capture's own protocol through the Skill tool - the ANALYZE step's protocol owner, which a fresh session has never read Remaining weak points, tier order: 1. <surface - symbol> - <tier> - <the action, one line>The percentage is the proxy, pinned behavior is the goal: never pad with assertion-free tests, never weaken or delete an existing test (one exception: a spec the step-2 red-check just PROVED vacuous - the check exists to authorize exactly that rewrite or delete), never widen exclusions or lower the requirement to reach SATISFIED - those two belong to the user, recorded in the doc.
A testability refactor stays behavior-preserving - the existing suite is green before and after - and the tier on each weak point is the routing authority: no silent upgrade of a small gap into a rewrite, no downgrade of a structural one past its approval gate.
Rules
- The main session is the only orchestrator; the seats it dispatches carry no Agent tool, so the fan-out stays flat.
- The instrumented run never enters a seat's dispatch brief - measurement is the capture's, in the main session, in both modes.
- Implementers keep writing each task's tests in every build flow (the
habits-done-gatebar) - this loop is the deliberate catch-up cadence, not a substitute for that. - Keep this skill orchestration only: measurement judgment lives in the capture; build knowledge lives in the domain seats and house skills. A pure code-quality polish is
loop-code-quality; architecture weaknesses areloop-architecture-quality's.