Harden coordination parsing after PR #339 audit

[justin808]

Summary

• make the coordination-declaration gate ignore variable-length backtick/tilde fences and indented code examples without relaxing valid top-level or bullet declarations
• return precise near-miss and invalid UTF-8 input errors, and broaden the <PROJECT> legacy guard to natural repository-name paraphrases
• anchor all nine contract/helper heading extractors proven vulnerable by caller-level mutation tests

Why

The post-merge audit of #339 confirmed that the merge itself is healthy, but found that a documentation example could still satisfy the new runtime gate. It also confirmed the five deferred extractor sites in #340 and reproduced the same positional bug in four additional callers.

This PR is intentionally limited to those parser, diagnostic, and contract-test hardening changes. It does not change coordination applicability or the broader #401 policy work.

Verification

• ruby skills/pr-batch/bin/coordination-declaration-contract-test.rb
• ruby skills/pr-batch/bin/goal-completion-contract-test.rb
• AGENT_WORKFLOWS_SOURCE_CHECKOUT=1 ruby skills/pr-batch/bin/model-routing-contract-test.rb
• ruby skills/pause/bin/pause-prompt-test.rb
• ruby skills/pr-batch/bin/coordination-telemetry-contract-test.rb
• ruby skills/pr-batch/bin/review-wave-contract-test.rb
• ruby skills/plan-pr-batch/scripts/check_goal_prompt_size.rb
• bin/validate

Fixes #340
Fixes #357

[coderabbitai]

Warning

Review limit reached

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

Next review available in: 9 minutes

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: feb36732-561d-4c51-8b4a-67fba772093b

📥 Commits

Reviewing files that changed from the base of the PR and between 845ab02 and 7b76262.

📒 Files selected for processing (8)

• skills/pause/bin/pause-prompt-test.rb
• skills/plan-pr-batch/scripts/check_goal_prompt_size.rb
• skills/pr-batch/bin/coordination-declaration
• skills/pr-batch/bin/coordination-declaration-contract-test.rb
• skills/pr-batch/bin/coordination-telemetry-contract-test.rb
• skills/pr-batch/bin/goal-completion-contract-test.rb
• skills/pr-batch/bin/model-routing-contract-test.rb
• skills/pr-batch/bin/review-wave-contract-test.rb

---

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

Overview: This PR hardens the coordination-declaration gate (skills/pr-batch/bin/coordination-declaration) added in #339, plus anchors nine heading/section extractors across contract-test helper scripts that were previously vulnerable to substring-match false positives (e.g. a heading name quoted in a comment binding the extractor to the wrong location). Three main changes:

1. visible_lines state machine — a new CommonMark-aware pass that tracks fenced code blocks (backtick/tilde, variable length, tab/space indentation) and list-item content columns, so declarations inside code examples or indented code blocks no longer satisfy the gate while genuine bulleted/nested declarations still do.
2. Near-miss diagnostics — `coordination:`, **coordination:**, Coordination:, and wrong-dash variants now produce a precise "near-miss" blocker instead of the generic missing-declaration message.
3. Input hardening — invalid UTF-8 handoff input now fails cleanly (exit 64) instead of crashing, and the <PROJECT>/repository-name guard in the goal-completion contract test now matches paragraph-scoped, more paraphrase-tolerant patterns.

Code quality: Very well tested — the PR adds ~340 lines of adversarial contract tests covering tabs, mixed space/tab indentation, nested lists, dedents, fence-info edge cases (backticks vs. tildes), and over-indented closers, which gives strong confidence in the parser's correctness even though I couldn't execute the Ruby suite in this environment (sandboxed) to confirm green. The manual trace of column_after_padding, expand_leading_whitespace, and the fence-open/close logic checks out against CommonMark's tab-stop-4 and list-item-content-column rules.

Risk/blast radius: Low — this is internal repo tooling that gates the format of the batch coordinator's own handoff text; it doesn't touch user-facing product code, doesn't execute untrusted input, and has no network/shell-injection surface.

Notes left inline (all non-blocking, quality/maintainability):

• visible_lines is a fairly dense hand-rolled parser; a short header comment mapping it to the specific CommonMark rules it implements would help future maintainers who don't want to re-derive the logic from the test suite.
• read_handoff manually raises Encoding::InvalidByteSequenceError with just a message (works, and is covered by the new UTF-8 test, but the exception's error_bytes/encoding attributes will be nil if anything downstream ever inspects them).
• The new exact-string assertion on the --handoff usage error couples a test to optparse's internal message wording.
• pause-prompt-test.rb's heading-anchoring fix only covers #-prefixed markdown headings; the plain-prose anchors used elsewhere in that same file still use the old unanchored substring search, leaving a narrower version of the original bug open there.

No correctness bugs or security issues found in the core parsing logic.

[justin808]

Address-review closeout for exact head 7b762627e87e5e122184c438d0e0e73ef66d3c42.

Mattered: none. Claude reported no correctness or security bugs.

Optional / declined at the final-candidate gate:

• Harden coordination parsing after PR #339 audit #410 (comment) — parser-orientation comments would be maintainability-only; the 63-test contract suite and independent generated corpus are the executable specification.
• Harden coordination parsing after PR #339 audit #410 (comment) — the synthetic encoding exception is contained within the CLI boundary; no downstream consumer observes richer exception attributes.
• Harden coordination parsing after PR #339 audit #410 (comment) — exact OptionParser wording is intentionally pinned as the public CLI contract requested by Converge contract-test section extraction on anchored heading matches (9 sites) #340.
• Harden coordination parsing after PR #339 audit #410 (comment) — plain-prose locators were independently mutation-tested and intentionally preserved; the audit changed the nine Markdown heading/fence callers.

All four threads were replied to and resolved with rationale. CodeRabbit reached a terminal rate-limit disposition and produced no findings. Independent current-head adversarial review covered 2,790 marker-padding cases, 126 ancestry cases, and 900 fence/list transitions with zero mismatches. Future scans start after this comment.

[justin808]

No description provided.