Problem

Surfaced during the 2026-05-19 v0.0.156 release doc sweep: several patterns and conventions that are practiced consistently in this repo aren't actually documented anywhere reviewers / new contributors / AI agents would find them. Each individual item is small, but together they're the difference between a clean handoff and a contributor (or maintainer working from cold context) having to learn-by-friction.

The highest-priority items were added to CLAUDE.md and CONTRIBUTING.md in PR for v0.0.156 release:

• "No known bugs." convention (KNOWN_ISSUES.md + SKILL.md empty-table handling)
• Skip-changelog: commit trailer for the changelog gate
• First-time-contributor action_required CI gate

This issue tracks the remaining items.

Items to document

1. CodeRabbit reply workflow nuances

CLAUDE.md mentions @coderabbitai prefix replies but doesn't capture:

• Push the fix BEFORE replying — otherwise the reply lands on a thread that still shows old code; gives reviewers an inconsistent picture
• Reply per-thread, even on declines — even if you're not making the change, post a brief reason on the specific thread (avoids the "boomerang" where CR re-raises the same finding next pass)
• "Outdated" auto-resolution — when CR-flagged code changes shape (lines move / rewrite), GitHub auto-marks the comment thread outdated and the comment becomes line=null in the API. CR doesn't post a follow-up confirmation; the implicit signal is "the position is gone, the comment is moot". This is normal — no human action needed.
• @coderabbitai pause for very-active PRs — useful when iterating fast to avoid CR posting on every push

2. JSON output as a public API contract

vera test --json, vera check --json, vera verify --json produce JSON for downstream CI consumers. Currently no documentation states which fields are stable vs. which are experimental. The new TestSummary.unlisted_errors (added in v0.0.156, PR #685) is a concrete example — it's a public API contract now and breaking it would affect CI pipelines.

Suggested: a section in TESTING.md or a new spec/JSON-OUTPUT.md that:

• Lists the stable fields per --json command
• Notes stability guarantee shape (e.g. "fields will only be added, never removed without a major version bump")
• Documents summary.unlisted_errors, summary.failed, summary.skipped, etc. specifically

3. Doc-count gate awareness for [Unreleased]

scripts/check_doc_counts.py checks numbers in TESTING.md / ROADMAP.md / README.md against live test counts. Any PR adding tests will trip the gate. Currently you only learn this from CI failure; the conventions aren't stated next to the test-writing instructions in CONTRIBUTING.md.

Suggested: add a brief note in CONTRIBUTING.md "Running Tests" section.

4. Modular verification design principle (explicit statement)

spec/06-contracts.md §6.4.2 says functions are verified "modularly" — each function is verified against its declared contract, with callees assumed to honour theirs. This is correct but worth making more prominent: it explains why main calling a buggy double still verifies as Tier 1 (the bug is contained to double's body-vs-contract mismatch).

This came up during PR #685 review when I was confirming the bug fix worked correctly. Currently a careful reader can derive this from the existing prose, but it's not signposted.

Suggested: a single sentence in §6.4.2 making the modular guarantee explicit, with the main / double example.

5. Two-instance review workflow

The 2026-05-18 compiler review document referenced a "two-instance workflow" (strategic Claude.ai session → execution Claude Code instance). This pattern isn't documented in the repo. May be a personal workflow (userPreferences was referenced as the source), in which case skip; otherwise worth a CLAUDE.md note for anyone trying to reproduce the pattern.

Acceptance criteria

For each of items 1-4 above:

• A concrete addition to the relevant doc file (CLAUDE.md / CONTRIBUTING.md / TESTING.md / spec/06-contracts.md)
• Cross-referenced from the index of the file if applicable

Item 5 closed with a one-line decision: documented, or "out of repo scope".

Provenance

Surfaced during the 2026-05-19 v0.0.156 release doc sweep when the user explicitly asked "write down anything that is in context or known but isn't written down in the repo". The highest-impact items landed inline in the release PR; this issue captures the remaining items so they don't get lost.