[hivecommons-hive]

Coverage documentation

npm run test:coverage on main @ 88241f4 reports 100 % lines / 99.75 % branches (1652/1656), and the four "uncovered" branches are close.ts:39, reopen.ts:36, approve.ts:504, auth.ts:220. All four arms are driven by the suite; coverage/lcov.info carries a negative hit count for each (BRDA:39,3,1,-3, BRDA:36,3,1,-1, BRDA:504,80,1,-6, BRDA:220,13,1,-51), and the e2e run repeats the last two (-28, -43). The folded finding on #507 asked for this to be recorded in docs/contributing.md so the lines stop being re-triaged as gaps; #500 merged without it.

This adds a "Phantom uncovered branches after an await" section to the Testing chapter of docs/contributing.md: the four lines, the mechanism, an awk recognizer for negative BRDA records, a minimal reproduction, and the instruction not to add /* v8 ignore */ markers or lower the branch floor for them.

Files: docs/contributing.md only. No src/, test or dist/ change. Disjoint from #510 (src/utils/auth.ts, dist/index.js).

Root cause (reduced locally, @vitest/coverage-v8 5.0.4)

The prior finding guessed "an if after a multi-line awaited condition". Reduction shows formatting is irrelevant; the trigger is an await that is only sometimes reached before the if:

export async function gate(a: boolean, b: boolean): Promise<string> {
  const ok = a || (await Promise.resolve(b))
  if (ok)
    return 'yes'
  return 'no'
}

gate(true,false) ×3, gate(false,true), gate(false,false) → BRDA:3,1,0,4 / BRDA:3,1,1,-2. V8 opens a new block-count range where the async function resumes, so the range enclosing the if counts only the two calls that awaited; the then-block counts all four; the implicit else (enclosing − then) is −2 although it ran once. A ternary with an await in each arm (approve.ts:504, auth.ts:220 shape) is miscounted the same way (enclosing = resumptions from the last await only; the else read 1 when it ran 6 times in the reduction). An explicit else { … } block is counted correctly because it owns a range of its own. A trivial unconditional await before the if is counted correctly.

Verification (this branch, local)

• npx vitest run __tests__/docsYamlExamples.test.ts __tests__/version.test.ts __tests__/configurationDocs.test.ts (the suites that walk docs/*.md): 3 files / 130 tests pass
• npx eslint docs/contributing.md: clean
• The awk recognizer in the note, run on coverage/lcov.info from main @ 88241f4, prints exactly the four records above

Related Issue

Refs #507 — ticks the docs/contributing.md box of the folded BRDA finding on that tracker. The issue's own two boxes (auth.ts:24) are #510's. The remaining box of the folded finding, a vitest-dev/vitest report with the reproduction above, needs a human: this lane cannot file outside cncf/prow-github-actions.

---

Filed by quality agent (hold-gated mode). Human review required.

— hive: agent=quality backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Important

Held for human review by the hive's ACMM level gate.

This PR was opened by the "quality" agent while Hive policy required a human checkpoint for that agent. Agent PRs are held at ACMM L3–L5; an outreach PR that targets a repository this hive does not manage is held at every level because it publishes project-facing communication into someone else's project.

Hive will keep the hold label until a human removes it. Operators can make a deliberate one-off release during an ACMM level change with release_level_holds=true, but level changes never release this hold automatically.

[github-actions]

Please add a kind label with /kind feature, /kind failing-test or /kind cleanup.

[mrbobbytables]

Copilot review performed under the maintainer's explicit authorization to update, review, release reviewed holds, and merge eligible PRs in this cleanup.

The documentation records the negative-count BRDA artifact, a recognizer and a reduced reproduction, without lowering thresholds or hiding covered branches. The upstream-report follow-up remains independently tracked in #550.

Verified successful build-test, e2e-coverage and DCO results on head 3ffa788. Any folded issue findings remain assigned to the canonical destinations in the updated scope tables.