Add coverage-of-change gate to verify and a commit-message policy

[justin808]

Fixes #256
Fixes #318

Why

verify proved the existing suite stayed green, but nothing checked whether the change under review was covered by any test — a PR could fix real behavior, pass every gate, and ship zero assertions on the thing it fixed (#256, worked example: react_on_rails PR #2489, where the fix is still uncovered four months later). Separately, a 30-commit Shakapacker audit found the dominant AI-slop signal wasn't code defects but oversized generated commit messages with decision logs and QA receipts duplicated permanently into Git history (#318).

This PR adds:

1. A Coverage-Of-Change Gate to skills/verify/SKILL.md: for any non-docs diff, require either a named test demonstrated to fail without the change (revert-and-watch-it-fail), or an explicit skip from a closed four-code set (MECHANICAL, GENERATED, NOT_OBSERVABLE, NO_HARNESS). Free-text "no test needed" cannot satisfy the gate. The gate routes into skills/tdd/SKILL.md (new "Coverage-Gate Entry Point" section) instead of reimplementing the RED/GREEN loop, and emits a COVERAGE <test path/name> fails without change / COVERAGE SKIPPED <code> receipt in the verify output block. A repo seam (coverage_of_change.never_skip_paths in .agents/agent-workflow.yml) can tighten the gate by forbidding skips on named paths, but cannot loosen or disable it.
2. A new canonical workflows/commit-messages.md: an ownership map for where commit rationale, decision logs, QA receipts, and review dispositions belong (cross-referencing the existing Codex Decision Log, qa-evidence v2, and priority-finding-dispositions v1 conventions already in workflows/pr-processing.md rather than duplicating them); a concise subject+Summary+Why+issue-linkage commit contract; a qualitative (non-line-count) concise mode for small diffs; duplicate-section detection/collapse guidance between commit body and PR description; and explicit provenance/changelog preservation rules. skills/verify/SKILL.md gets a matching "Commit Message Contract" step and COMMIT-CONTRACT <concise|full>: <reason> receipt, satisfying Keep generated commit messages proportional and store audit receipts outside Git history #318's "at least one authoring/closeout skill enforces or validates the concise commit contract" criterion.

Decision Log

• skills/ship/SKILL.md does not exist in this repo, and was not created. The batch envelope that spawned this lane listed it as a possible wiring target, but /ship belongs to a different pack (gstack), not agent-workflows. skills/verify/SKILL.md is this repo's actual authoring/closeout surface, so the commit-message contract is wired there instead.
• workflows/commit-messages.md is the new canonical home for Keep generated commit messages proportional and store audit receipts outside Git history #318's policy, rather than folding it into workflows/pr-processing.md. pr-processing.md already defines the receipt formats this policy references (Decision Log, qa-evidence v2, priority-finding-dispositions v1) but is owned by a different lane in this batch and is large enough that adding a full commit-message contract to it would blur its scope. The new file is picked up automatically — bin/install-agent-workflows installs workflows/* and bin/agent-workflow-seam-doctor globs workflows/**/*.md — so no registry file needed a matching update.
• Keep generated commit messages proportional and store audit receipts outside Git history #318 acceptance criterion 3 (fixtures proving a small diff's QA evidence stays replayable without being copied into the commit body) is deliberately deferred. Fixtures live under test/fixtures/**, which this lane does not own. Filed as #324, with the concrete direction (fixture shape, validator pattern to follow) written into the issue so it's actionable without this PR's context. Criteria 1, 2, and 4 are delivered in full.
• skills/tdd/SKILL.md carries a <!-- Keep this skill in sync with workflows/tdd.md --> marker, but workflows/tdd.md is owned by a different lane. The new "Coverage-Gate Entry Point" section was added as a new trailing section rather than edited into the mirrored Core Loop/Guardrails/Before Pushing/Done text, so those sections stay a byte-for-byte match with workflows/tdd.md. workflows/tdd.md itself does not yet have an equivalent pointer back to verify's gate — a follow-up for whichever lane owns workflows/tdd.md next.
• No new bin/** helper was added for either issue. The coverage gate and commit contract are both agent-followed prose steps (revert/restore, RED/GREEN evidence, duplicate-section comparison), consistent with bin/** being outside this lane's owned paths; commit-messages: add fixtures proving QA-evidence replay survives commit-body duplication collapse #324 covers the one piece (fixtures + a validator) that would need new script surface.
• CHANGELOG.md was intentionally left untouched. It isn't in this lane's owned-paths list and wasn't part of the coordinator's deliverable steps; flagging it here so batch closeout (or update-changelog) can add an entry for this PR alongside the batch's other lanes.
• A transient flake in skills/pr-batch/bin/agent-coord-bounded-test.rb (unrelated to this PR, outside this lane's owned paths) was found while manually reconstructing the full bin/validate run and filed as #338 rather than fixed here, with full repro/non-repro evidence in the issue. See the Verification section below for the diagnostic detail.

Verification

Local commands run from this branch's head, matching AGENTS.md → Validation. .agents/bin/lint passed clean first:

$ .agents/bin/lint
== rubocop 1.87.0 ==
117 files inspected, no offenses detected
== shellcheck 0.11.0 ==
(no shellcheck output — no shell files changed by this PR)
== markdownlint-cli2 0.23.2 ==
Summary: 0 issues in 0 files

bin/validate (mandatory pre-commit gate). The full script (bin/validate) runs longer than this environment's 10-minute single-command cap even under the correct locale, so instead of truncating coverage I ran every one of its constituent commands individually, in the exact order bin/validate defines them (verified by reading the script), each to completion with a captured exit code. Every command exited 0 with real "N runs, M assertions, 0 failures, 0 errors" output, except two flakes fully diagnosed below. Representative real output:

== license == / == skill frontmatter == / == native plugin manifests == / == OpenAI picker metadata == / == host adapter syntax ==
PASS 28 skills
PASS native plugin manifests: 28 skills under scw
PASS 27 OpenAI agent metadata files
PASS host adapter syntax

== validator unit tests ==
280 runs, 2404 assertions, 0 failures, 0 errors, 0 skips
30 runs, 101 assertions, 0 failures, 0 errors, 0 skips
9 runs, 25 assertions, 0 failures, 0 errors, 0 skips
12 runs, 38 assertions, 0 failures, 0 errors, 0 skips

== status unit tests == / == repository security policy ==
10 runs, 52 assertions, 0 failures, 0 errors, 0 skips
7 runs, 75 assertions, 0 failures, 0 errors, 0 skips
9 runs, 34 assertions, 0 failures, 0 errors, 0 skips

== push-downstream unit tests ==
110 runs, 598 assertions, 0 failures, 0 errors, 0 skips   # see note below on #281

== agent workflow drift unit tests == / == solution docs == / == review finding schema ==
73 runs, 1161 assertions, 0 failures, 0 errors, 0 skips
14 runs, 27 assertions, 0 failures, 0 errors, 0 skips  / PASS 2 solution docs
34 runs, 188 assertions, 0 failures, 0 errors, 0 skips  / PASS review finding schema

== installer/status/upgrade tests ==
bin/install-agent-workflows-test.bash: 35 runs, 184 assertions, 0 failures, 0 errors, 0 skips (+ 59 named PASS lines)
bin/agent-stack-test.bash / bin/agent-workflows-doctor-test.bash / bin/agent-stack-doctor-test.bash: all EXIT:0, no failures anywhere in output

== fixture seam validation ==
PASS agent workflow seam is complete

== downstream registry dry-run ==
EXIT:0

== helper tests == (36 files under bin/** and skills/**/bin/**)
All EXIT:0, 0 failures, 0 errors — except one transient flake, see below.

== rubocop 1.87.0 ==
117 files inspected, no offenses detected

Pre-existing failure #1 — bin/push-downstream-test.rb locale issue (already tracked, not caused by this PR). Under this shell's default LANG=""/C locale, test_policy_apply_compares_validated_non_ascii_policy_content_as_bytes raises Encoding::CompatibilityError: incompatible character encodings: US-ASCII and UTF-8 at bin/push-downstream-test.rb:1576. I reproduced this on a clean origin/main checkout (this branch's changes stashed) and the coordinator independently reproduced it too, on base 282a87a, getting the identical 110 runs, 595 assertions, 0 failures, 1 errors / same Encoding::CompatibilityError at the same line. It's already tracked as #281 ("bin/push-downstream-test.rb is locale-dependent and aborts bin/validate when LANG is unset"). Running with LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 avoids it entirely — the command above shows 0 failures, 0 errors under that locale.

Transient flake #2 — skills/pr-batch/bin/agent-coord-bounded-test.rb (unrelated, not reproducible, newly filed as #338). This file failed 2 of 14 tests once, mid-sequence, with process-group timing signatures (fake helper did not start; empty stdout where output was expected) — consistent with system load, not a logic bug. I verified it is not caused by this PR: (a) re-running the single failing test immediately after passed (1 runs, 7 assertions, 0 failures); (b) re-running the full file in isolation on a clean main checkout (this branch's changes stashed) passed clean (14 runs, 81 assertions, 0 failures, 0 errors); (c) re-running the full file in isolation on this branch (changes present, unstashed) also passed clean (14 runs, 81 assertions, 0 failures, 0 errors). This branch touches zero Ruby/bin/**/skills/pr-batch/** files, so there's no plausible causal link. Filed as #338 with full repro evidence and a suggested direction (likely a fixed short timeout that should tolerate contention).

Also ran, self-applying the new gate to this PR's own diff:

• COVERAGE SKIPPED NO_HARNESS: this change is prose policy in skills/*/SKILL.md and workflows/*.md; the repo's only automated checks for these files are frontmatter-shape validation (bin/validate) and markdown/prose lint (bin/lint), neither of which tests skill/workflow semantic content — no harness exists to assert on agent-followed instructions.
• COMMIT-CONTRACT full: multi-file policy change across two issues with several load-bearing design decisions (seam key shape, closed skip-code set, ownership map) — not a small/mechanical diff.

Confidence note

High confidence in the design and cross-references (verified against the existing Codex Decision Log / qa-evidence v2 / priority-finding-dispositions v1 conventions in workflows/pr-processing.md rather than inventing parallel ones); medium confidence in the exact coverage_of_change.never_skip_paths seam key name since this source pack doesn't define it for itself (single-operator mode) — a consumer repo adopting it is the real test. The one open gap is the deferred fixture criterion, tracked in #324.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@justin808, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: dd1c3dbf-5c03-4cb7-92d9-ab8fe3fe770e

📥 Commits

Reviewing files that changed from the base of the PR and between 282a87a and c6e2921.

📒 Files selected for processing (3)

• skills/tdd/SKILL.md
• skills/verify/SKILL.md
• workflows/commit-messages.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[claude]

Review Summary

This PR adds a Coverage-Of-Change Gate to skills/verify/SKILL.md (with a routing entry point in skills/tdd/SKILL.md) and a new canonical workflows/commit-messages.md policy, both wired via new COVERAGE/COMMIT-CONTRACT receipts. It's a prose-only, docs/policy change — no executable code, no .agents/agent-workflow.yml schema changes in this repo (the new coverage_of_change.never_skip_paths seam key is documented but not adopted here, consistent with "single-operator mode").

What it does well

• Closes a real gap: verify previously proved the existing suite stayed green without proving the new behavior was covered by anything.
• The closed four-code skip set (MECHANICAL/GENERATED/NOT_OBSERVABLE/NO_HARNESS) is a good design choice — it forecloses the "no test needed" free-text escape hatch that makes this kind of gate toothless in practice.
• Routes into tdd's existing RED/GREEN loop instead of reimplementing it — avoids drift between two "how to write a failing test" procedures.
• workflows/commit-messages.md's ownership map is a clean, well-cross-referenced fit with the existing Codex Decision Log / qa-evidence v2 / priority-finding-dispositions v1 conventions in workflows/pr-processing.md rather than duplicating them.
• Cross-references I spot-checked (Process Gap Disposition, checklist+replay, install/seam-doctor globbing of workflows/**/*.md) all resolve correctly — the PR isn't inventing terminology or pointing at things that don't exist.
• The PR description is unusually thorough about scope boundaries and defers what it can't own (fixtures in commit-messages: add fixtures proving QA-evidence replay survives commit-body duplication collapse #324) rather than half-implementing it.

Issues found (see inline comments for detail)

1. Overstated seam parity (skills/verify/SKILL.md:107): the new coverage_of_change.never_skip_paths key is described as matching the shape of autonomous_merge.human_review_paths, but the latter is actually parsed/enforced by bin/agent_doctor/autonomous_merge_policy.rb, while the new key has no corresponding parser anywhere — it's enforced only if an agent reading the SKILL.md prose chooses to honor it. The "cannot disable the gate" language should be qualified as policy-level, not structurally enforced.
2. Ambiguous docs-only exemption boundary (skills/verify/SKILL.md:88): it's unclear whether the exemption covers skills/**/workflows/** prose files or only the repo's documented docs/** directories. Telling sign: the PR's own diff (which is entirely SKILL.md/workflows/*.md) didn't claim the exemption — it used NO_HARNESS instead — suggesting the boundary needs to be spelled out explicitly rather than left implicit.
3. Minor gap: the four skip codes don't cleanly describe a test-only diff (fixing/adding a test with no accompanying production change), where there's no separate "test that covers the behavior" to point to.

Other notes

• This is a trust-based/self-attested gate (like the rest of this repo's prose-skill pattern) — there's no automated check that an agent actually performed the stash/revert-and-watch-it-fail dance before writing the COVERAGE receipt. That's consistent with how the rest of the repo works, not a regression, but worth naming as a known limitation given the PR's own stated motivation (catching unverified claims).
• No security concerns — this is documentation/prose only, touches no executable paths, secrets, or CI permissions.
• Verification evidence in the PR description is thorough (full bin/validate breakdown, two pre-existing/unrelated flakes diagnosed and filed as separate issues rather than papered over).

[claude]

Review Summary

This PR adds a Coverage-Of-Change Gate to skills/verify/SKILL.md (routing into skills/tdd/SKILL.md via a new "Coverage-Gate Entry Point" section) and a new canonical workflows/commit-messages.md policy for commit/PR receipt placement, wired into verify via a "Commit Message Contract" step. This is a prose/policy change to agent-followed skill specifications rather than executable code, so the review below focuses on internal consistency, correctness of cross-references, and clarity for the agents that will follow these instructions.

What's good

• Cross-references check out. I verified every reference this PR makes to existing conventions actually exists as described: Codex Decision Log and Batch Handoff Format in workflows/pr-processing.md, the qa-evidence v2 and priority-finding-dispositions v1 hidden markers, the checklist+replay Process Gap Disposition mechanism, bin/agent_doctor/autonomous_merge_policy.rb's HUMAN_REVIEW_PATH_KEYS/HUMAN_REVIEW_REASONS allowlist (used as the contrast case for the new unenforced coverage_of_change.never_skip_paths seam), and skills/update-changelog/SKILL.md. None of these are stale or invented.
• The tdd sync-marker discipline is honored. skills/tdd/SKILL.md carries <!-- Keep this skill in sync with workflows/tdd.md -->, and the PR correctly appends the new "Coverage-Gate Entry Point" as a trailing section rather than editing the mirrored Core Loop/Guardrails/Before Pushing/Done text — I diffed those sections against workflows/tdd.md and they remain byte-for-byte identical, exactly as the PR description claims.
• The gate's own self-application is consistent. The Coverage-Of-Change Gate declares that skills/**/workflows/** prose changes always count as non-docs source (never docs-only-exempt) even though they're Markdown — and the PR's own diff, being entirely within those directories, is correctly self-scored as COVERAGE SKIPPED NO_HARNESS per the PR body rather than claiming a docs exemption.
• Ownership map in workflows/commit-messages.md is a clear, non-duplicative table and the "when in doubt, prefer the PR description over the commit body" default is sensible given commit messages are much harder to fix after merge.

Issues found (posted inline)

1. Inconsistent Output Format example (skills/verify/SKILL.md, Output Format section): the example shows a FAIL <repo formatter check> with an unresolved "Next fix" step, but still includes populated COVERAGE/COMMIT-CONTRACT receipt lines. Per the new Instructions step 7 ("once the commands above are green, apply the Coverage-Of-Change Gate"), those receipts shouldn't appear in the same summary as an outstanding failure. An agent copying this example literally could produce reports that fill in coverage/commit receipts before the verification loop is actually clean.
2. Missing loop-back after invoking tdd (skills/verify/SKILL.md, Coverage-Of-Change Gate section): when the gate has no test to name and routes into tdd to add a RED test, the newly added test (and any resulting code) isn't explicitly sent back through the Default Verification Order (steps 4-6) before the final report. Since step 7 gates coverage-checking on "the commands above are green," a stale green from before the tdd detour could ship a new file that was never linted/validated.

Minor observations (not blocking)

• The four skip codes (MECHANICAL, GENERATED, NOT_OBSERVABLE, NO_HARNESS) are still entirely self-reported with no machine enforcement — the PR is explicit about this limitation (and about coverage_of_change.never_skip_paths being prose-only), so this is a known, disclosed tradeoff rather than an oversight, but worth keeping in mind as the actual strength of the gate against the "no test needed" loophole it's meant to close (verify: add a coverage-of-change gate (a green PR can ship zero tests for the behavior it fixed) #256) depends entirely on agent compliance.
• No bin/** validator was added for either the gate or the commit contract, consistent with the PR's stated scope and deferred to commit-messages: add fixtures proving QA-evidence replay survives commit-body duplication collapse #324 for the fixture/validator follow-up — reasonable given the stated lane boundaries, but it does mean nothing here is enforced outside of an agent choosing to follow the prose.

Security / performance

Not applicable — this PR only changes prose specification files (skills/*/SKILL.md, workflows/*.md) that guide agent behavior; there is no executable code, no new dependencies, and no runtime performance surface.

[claude]

Review Summary

This PR is a pure prose/policy change (no code, no tests — as expected for a skills/**/workflows/** diff) adding two things to skills/verify/SKILL.md: a Coverage-Of-Change Gate (named-failing-test or one of four closed skip codes) and a Commit Message Contract pointing to a new canonical workflows/commit-messages.md, plus a small routing addition to skills/tdd/SKILL.md.

What I verified

• All internal cross-references resolve: Codex Decision Log, qa-evidence v2, priority-finding-dispositions v1, Process Gap Disposition/checklist+replay, and Batch Handoff Format all exist in workflows/pr-processing.md as cited; skills/update-changelog/SKILL.md and the changelog policy key both exist.
• The new workflows/commit-messages.md file is picked up automatically by bin/install-agent-workflows (copy_children_preserving_unrelated "$repo_root/workflows" "$target/workflows") — no registry update needed, as the PR body claims.
• The new coverage_of_change.never_skip_paths seam key is genuinely "prose-level, not machine-enforced" as disclosed: bin/agent-workflow-seam-doctor's policy_issues only rejects unresolved placeholder values for unknown top-level keys, not the keys themselves, so this won't break seam validation for consumer repos — consistent with the PR's own caveat.
• The mirrored sections in skills/tdd/SKILL.md (Core Loop/Guardrails/Before Pushing/Done) remain byte-for-byte identical to workflows/tdd.md; the new "Coverage-Gate Entry Point" section was correctly appended rather than interleaved, so the sync marker claim holds.
• Step-number cross-references elsewhere in the repo don't hardcode verify's old step numbers, so renumbering steps 7-9 doesn't break other files.

Issues found (posted inline)

1. skills/verify/SKILL.md:105 — The flaky-test-fix branch of the "Test-only diffs" rule asks the agent to "temporarily reintroduce the flake condition and confirm the test now fails." Flakes are by definition not reliably reproducible on demand, and unlike the main verification loop (which has an explicit 3-cycle stop rule), this branch has no bound on reproduction attempts — an agent could loop indefinitely trying to force a flake before falling back to a skip code.
2. skills/verify/SKILL.md:88 (minor/style) — The gate's trigger-condition paragraph is a single dense run-on covering three distinct ideas (when the gate applies, why prose skills/workflows files count as non-docs, and a self-referential example). Given the rest of the file favors bullets for multi-clause rules, this would be more reliably followed as a short list.
3. skills/verify/SKILL.md:126 (nit) — Cites "Instructions steps 4 and 7" for why FAIL runs never reach the receipts, but step 8 (Commit Message Contract) is equally gated and isn't mentioned.

Overall

The design is well cross-referenced against existing conventions rather than inventing parallel ones, and the PR's own Decision Log is unusually transparent about scope boundaries and deferred work (#324, #338). No correctness or security concerns — the only real risk is #1 above (an open-ended reproduction loop for flaky-test fixes), which is worth tightening before merge; the other two are style nits.

[claude]

Review Summary

This PR adds a Coverage-Of-Change Gate to skills/verify/SKILL.md, a matching Coverage-Gate Entry Point in skills/tdd/SKILL.md, and a new canonical workflows/commit-messages.md policy for commit-message shape and receipt placement. This is a prose/policy change only (no executable code), so the review focused on internal consistency, cross-reference accuracy, and whether the described enforcement will actually bite in practice.

Cross-reference verification

I checked every concrete claim the PR makes against repo state rather than taking the PR description at face value:

• workflows/pr-processing.md does define Codex Decision Log, qa-evidence v2, priority-finding-dispositions v1, Batch Handoff Format, Process Gap Disposition, and checklist+replay exactly as referenced -- no dangling references.
• .agents/agent-workflow.yml does define autonomous_merge.human_review_paths/thresholds and changelog: "CHANGELOG.md"; bin/agent_doctor/autonomous_merge_policy.rb does define HUMAN_REVIEW_PATH_KEYS/HUMAN_REVIEW_REASONS as described (used as the "how a real parser would look" contrast for the new, intentionally-unenforced coverage_of_change.never_skip_paths seam).
• skills/update-changelog/SKILL.md exists.
• bin/install-agent-workflows installs workflows/* and bin/agent-workflow-seam-doctor globs workflows/**/*.md, confirming the new workflows/commit-messages.md file is picked up automatically without a registry update, as the Decision Log claims.

All checked out -- the cross-referencing is accurate, which matters a lot for a doc whose entire job is to be a reliable pointer graph for other agents.

Code quality / correctness

• Instruction step numbering (steps 7-9 inserted into skills/verify/SKILL.md) and the routing back to step 4 for tdd-added files is internally consistent with the existing loop-counter logic in step 6.
• The two Output Format examples (failing run vs. fully green run) are a nice clarity improvement over the old single example, and correctly reflect that a run stops at first FAIL before receipts are ever produced.
• Left 3 inline comments -- one design concern about how much real enforcement the gate provides for the repo's own predominant content type, one practical gap in the "revert one hunk" recipe for entangled diffs, and one minor doc-completeness note about multi-behavior diffs in the Output Format examples.

Security / risk

No traditional security issues (this is instructional prose, not executable code). The main risk worth naming: the gate is entirely self-reported/self-graded by the agent doing the work -- the PR is explicit that coverage_of_change.never_skip_paths "has no parser anywhere in this pack" and only "takes effect ... if the agent following this skill reads and honors the prose." Combined with NO_HARNESS being the honest answer for most skills/**/workflows/** changes (see inline comment), the gate's practical enforcement is narrower than the PR summary might suggest. That's a reasonable tradeoff for a prompt-only pack, but worth stating as a known limitation rather than leaving it implicit.

Performance

N/A -- no executable code paths changed. The gate does add real per-PR cost going forward (revert-hunk / rerun / restore / rerun, twice per distinct behavior), which is an intentional tradeoff for coverage rigor, not a performance bug.

Test coverage

The PR self-applies its own new gate to its own diff (COVERAGE SKIPPED NO_HARNESS, COMMIT-CONTRACT full) and the description documents a very thorough manual bin/validate run, including full diagnosis of two pre-existing/unrelated flakes (#281, newly-filed #338) rather than papering over them. That's a strong verification writeup for a change with no automated harness to lean on.

Overall: solid, well-cross-referenced policy work with a fair amount of self-awareness about its own limitations (already flagged in the Decision Log). The inline comments are refinements, not blockers.

[justin808]

QA Evidence — independent Batch QA Lane (checker-aw-f)

Independent check by an agent that did not write this code, re-run from a detached checkout of c6e2921827797ebcaca7effef1503af7f45f9b7f. Evidence bound to this head; earlier passes against 63bca6ca, 6928fd30, and ebdc2b92 were discarded and the affected checks re-run here.

Automated checks

LANG=en_US.UTF-8 bin/validate → exit 1, aborting at bin/check-agent-workflow-drift-test.rb#test_git_probes_fail_closed_when_they_time_out with Errno::ENOENT ... hanging-git/git.pid (73 runs, 1160 assertions, 0 failures, 1 error).

I did not accept that as pre-existing on assertion. I verified it three ways: the file is untouched by this diff; the test reproduces the identical error on clean main @ 282a87a; and the failure is a stub-pid write race, not a behavior assertion. Pre-existing, not a lane defect.

Because bin/validate stops on first failure, everything after that point was skipped, so I ran every remaining section explicitly against this head:

• 47 PASS, including rubocop _1.87.0_ clean, the full skills/pr-batch/** helper suite, and agent-coord-bounded-test.rb (the Flaky agent-coord-bounded-test.rb process-group timing tests under load #338 flake — passed here).
• 3 transient FAILs occurred while a 90-second timing experiment for PR Make merge readiness a binding hook gate and record lane closeout on SessionEnd #343 ran concurrently. Each was re-run individually with no competing load and passed clean: agent-stack-doctor-test.bash (6 runs, 31 assertions), completed-batch-audit-receipt-test.rb (70 runs, 572 assertions), pr-walkthrough-contract-test.rb (2 runs, 89 assertions) — all 0 failures.

No test harness exists for skills/verify or skills/tdd (each is SKILL.md + agents/ only, and bin/validate registers neither), so there is no changed-file test to run directly. That independently confirms the COVERAGE SKIPPED NO_HARNESS treatment this PR prescribes for its own section is factually accurate rather than a convenient claim.

Adversarial review of the gate

Closed skip-reason set — free text cannot satisfy it. Exactly four codes remain (MECHANICAL, GENERATED, NOT_OBSERVABLE, NO_HARNESS), stated as "only from this closed set" with "Free-text 'no test needed' never satisfies the gate". I could not construct a wording that slips through: the Output Format's one-line skip allowance is scoped to commands, and the added sentence requires the COVERAGE SKIPPED receipt to carry its own line regardless.

The new bounded-flake fallback is not a fifth skip code, and I could not reach it cheaply. Its receipt form is COVERAGE <test>: flake not reproduced in 3 attempts; evidence: …, not COVERAGE SKIPPED <code>, and line 114 states a test-only diff "is never itself grounds for one of the four skip codes above". Reachability is triple-gated: the diff must be entirely test files, and the change must be a fix to a previously broken/flaky test, and reproduction must fail 3 times, and the receipt must cite a real prior failing CI run/issue/commit. A production change cannot reach it (the diff is not test-only); a new regression test takes the first bullet, not the flake bullet. It cannot be used to dodge coverage on a non-flaky change.

Docs-only exemption is an allowlist, not a denylist. The gate skips only when every changed file is docs-only under the documented-docs-directory classification, and skills/**/workflows/** "always count as non-docs source … even when the diff is Markdown-only". I attacked this with mixed diffs, Markdown-only skills diffs, and files outside both carve-outs (root AGENTS.md, .agents/**, examples/**) — all fail the allowlist and the gate applies. The three-bullet split at this head preserves every condition from the prose version; nothing was dropped or softened.

Seam key can only tighten, and its honesty claim checks out. I confirmed independently that never_skip_paths and coverage_of_change have zero references anywhere in the pack, so "has no parser anywhere in this pack" is true. The contrast it draws is also accurate: bin/agent_doctor/autonomous_merge_policy.rb genuinely parses human_review_paths with HUMAN_REVIEW_PATH_KEYS (line 23) and HUMAN_REVIEW_REASONS (line 24) allowlists. The paragraph now qualifies itself as prose-level and not machine-enforced, and does not imply enforcement that does not exist.

Output Format and loop-back (this head's other two changes). The failing-run example carries only PASS/FAIL plus "Next fix" with no receipts, and the preamble states receipts "belong only in a fully green run's output, never alongside an unresolved FAIL" — it cannot be read as authorizing receipts beside a FAIL. The tdd loop-back is reachable from both entry points (Instructions step 7 and the Gate section), both targeting step 4, and both name formatter/lint, .agents/bin/validate, and the targeted test, so a freshly added test cannot slip past verification by arriving after the first green run. The cross-reference now correctly reads "steps 4, 7, and 8".

No brittle line-count limit (#318). No numeric line/character threshold anywhere in either file; workflows/commit-messages.md carries an explicit Non-Goal, "No brittle universal line-count limit."

No consumer-repo hardcoding. No bundle exec, npm/yarn, rake/rspec, package paths, labels, or branch names. Everything routes through .agents/bin/* seams and ${BASE_BRANCH}.

No contradiction with workflows/pr-processing.md. commit-messages.md defers rather than redefines, and all six cited anchors exist there: Codex Decision Log, QA Evidence, qa-evidence v2, priority-finding-dispositions v1, Batch Handoff Format, Process Gap Disposition.

Envelope: 3 files, no deletions or renames.

Residual observation (not blocking): enforcement of the gate, the seam, and the flake fallback is entirely prose-level — a non-compliant agent can cite irrelevant evidence and no code path checks it. The PR states this limitation plainly rather than overclaiming, which is the right disposition; noting it so it is visible at merge time.

[justin808]

Batch handoff — AW F 08-05 08:40 (lane skill-docs)

Final state: ready-human-review-required. All gates are clean; the only remaining blocker is a maintainer merge decision.

Gate	Result at head c6e2921827797ebcaca7effef1503af7f45f9b7f
pr-ci-readiness v2	READY (exact head)
autonomous-merge-eligibility	human-approval-required — triggered: architectural-product-judgment, public-compatibility
merge-assurance	eligible: false, verdict: BLOCKED — "auto merge authority lacks a qualifying exact-head autonomous verdict"
Evidence failures	none (clean policy result, not UNKNOWN)
Rollback	code-only-rollback-established

merge_authority for this batch was auto_merge_when_gates_pass. That authority does not apply here: the repo's own autonomous_merge policy in .agents/agent-workflow.yml triggers the gates above, so the batch terminates at human review rather than merging. Separately, the seam sets merge_submission: mode: merge_queue_only and no merge queue is enabled on main, so pr-merge-submit would refuse before mutation regardless.

QA: independent Batch QA lane (checker-aw-f, distinct from every maker) — qa-evidence v2 marker on this PR, status: satisfied, release_blocking: clear, bound to head c6e2921827797ebcaca7effef1503af7f45f9b7f.

Follow-up #356 records three deferred refinements to the coverage gate (NO_HARNESS dominance, multi-hunk revert fallback, multi-behavior receipts); #324 covers the deferred #318 fixture criterion. Neither blocks this PR.

coordination: unavailable — repo seam sets coordination_backend: "n/a" (.agents/agent-workflow.yml:10), single-operator source repo.

Completed-batch audit: not published. completed-batch-publication-preflight cannot run here for two independent reasons — there is no coordination status to supply (backend n/a), and no target is merged, which it refuses on its own.

Local merge-gate artifacts (CI-readiness / eligibility / assurance JSON) were transient and did not survive temp cleanup; regenerate from the helpers in skills/pr-batch/bin/ against base 282a87aaf4bf1dd602723efddc78252f7a138235.