docs(adr): fix compliance rule precision in turn-boundary-batching

[masami-agent]

Summary

Fixes two precision issues in docs/adr/turn-boundary-batching.md identified during PR #598 review but not resolved before merge.

Changes

§6.4 Rule 1 — adapter-layer scope clarification

Added a caveat clarifying that Rule 1 (broker forwards {prompt} verbatim) applies to the broker/dispatcher layer — i.e. from Dispatcher::submit onward. Adapter-level preprocessing that runs before {prompt} is constructed (e.g. resolve_mentions() in discord.rs) is not subject to this rule.

§6.4 Rule 8 — scope to retry-failed case only

Rule 8 previously stated that SendError must surface immediately. However, §2.5 designs a retry-once path where the first SendError triggers eviction + transparent re-send. Updated Rule 8 to explicitly state that only a failed retry surfaces ❌ + ⚠️ + Err.

Optional nits

• §3.2: Marked slack_ts_to_iso8601 as "(proposed helper)" since it does not exist yet
• Metadata: Reworded self-reference from "this ADR documents the design it lands" to "the ADR documents the design that PR implements"
• §6.6: Clarified threshold formula units — p95_batch_size (count) × avg_tokens_per_event (tokens) > 500 tokens

References

• obrutjack review
• masami-agent re-review
• chaodu-agent changes requested

Closes #754

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs(adr): fix compliance rule precision in turn-boundary-batching
• Source: docs(adr): fix compliance rule precision in turn-boundary-batching #755
• Status: moved to PR-Screening
• Generated at: 2026-05-06T08:31:28.593Z
• Discord thread: https://discord.com/channels/1488041051187974246/1501501451061559387

Screening report

## Intent

PR #755 tightens the wording in docs/adr/turn-boundary-batching.md so the ADR’s compliance rules match the actual design intent from prior review of PR #598.

The operator-visible problem is ambiguity: the ADR currently overstates two requirements in ways that could mislead future implementers or reviewers. Specifically, it blurs adapter preprocessing versus broker prompt forwarding, and it implies every SendError must surface immediately even though the design includes a retry-once path.

Feat

This is a docs improvement.

Behaviorally, it does not change runtime code. It clarifies the documented contract for turn-boundary batching:

• Rule 1 applies after {prompt} is constructed, from Dispatcher::submit onward.
• Adapter-level preprocessing such as mention resolution is outside that rule.
• Rule 8 only requires surfacing an error after the retry path fails.
• Minor wording fixes improve precision around proposed helpers, self-reference, and token threshold units.

Who It Serves

Primary beneficiaries are maintainers and reviewers.

Secondary beneficiaries are future agent implementers and runtime operators who need the ADR to describe the intended batching, retry, and dispatch behavior without creating false compliance failures.

Rewritten Prompt

Update docs/adr/turn-boundary-batching.md to resolve precision issues identified during review of PR #598.

Clarify that the “broker forwards {prompt} verbatim” compliance rule applies only once the dispatcher receives a constructed prompt, not to adapter-layer preprocessing before prompt construction. Clarify that SendError should surface to the user/operator only after the retry-once resend path fails, preserving the transparent first-retry behavior described elsewhere in the ADR.

Also apply small documentation precision fixes: label slack_ts_to_iso8601 as proposed if it does not yet exist, reword any confusing ADR self-reference, and make the batching threshold formula units explicit.

Keep the change documentation-only, scoped to the ADR, and ensure the resulting text is internally consistent with the retry and batching design.

Merge Pitch

This is a low-risk documentation correction that prevents future implementation drift. It closes the gap between the ADR’s compliance language and the actual design reviewed in PR #598.

The main reviewer concern is likely whether the revised wording accidentally weakens compliance requirements too much. Review should focus on whether the boundaries are precise: adapter preprocessing before prompt construction remains allowed, while broker/dispatcher mutation after prompt construction remains prohibited.

Best-Practice Comparison

OpenClaw principles that are relevant:

• Explicit delivery routing: relevant because the ADR needs clear boundaries around adapter, dispatcher, broker, and delivery behavior.
• Retry/backoff and run logs: partially relevant because the SendError rule must match the designed retry path and operator-visible failure behavior.
• Isolated executions: indirectly relevant if batching dispatch becomes tied to execution sessions.
• Durable job persistence and gateway-owned scheduling: not directly relevant to this PR, since it only corrects ADR wording.

Hermes Agent principles that are relevant:

• Self-contained prompts for scheduled tasks: relevant by analogy because prompt construction and forwarding boundaries must be explicit.
• Fresh session per scheduled run: only indirectly relevant if this ADR later governs scheduled or batched agent execution.
• Gateway daemon tick model, file locking, and atomic writes: not directly relevant to this documentation-only clarification.

The strongest best-practice alignment is precision around ownership boundaries. The ADR should make it clear which layer owns preprocessing, which layer owns dispatch, and when failures become user/operator-visible.

Implementation Options

Conservative option: Merge the PR as a narrow ADR wording fix.

This keeps the change documentation-only and accepts the current patch if the wording accurately reflects PR #598 review outcomes.

Balanced option: Merge the wording fix, then open a follow-up issue to audit the implementation against the clarified rules.

This preserves the low-risk docs correction while making sure the actual dispatcher, adapter, and retry behavior conform to the clarified ADR.

Ambitious option: Convert the clarified ADR rules into explicit compliance tests or review checklist items.

This would turn the ADR precision into enforceable guardrails, such as tests for retry-failed surfacing behavior and checks that prompt mutation does not occur after dispatcher submission.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative: merge docs fix only	High	Low	Medium	Medium	Low direct impact	Strong
Balanced: merge docs fix plus implementation audit follow-up	Medium	Medium	High	High	Medium indirect impact	Strongest
Ambitious: add compliance tests/checklist enforcement	Low	High	Highest	High	Medium indirect impact	Good later, probably too much for this PR

Recommendation

Use the balanced path.

Advance PR #755 as a focused documentation correction, assuming the diff matches the stated scope, and create or link a follow-up implementation audit for the clarified adapter/dispatcher boundary and retry-failed SendError behavior.

That sequencing keeps this PR mergeable while preserving the deeper reliability question for Masami or Pahud follow-up. The current item should not expand into test or runtime changes unless review finds the ADR text still contradicts existing behavior.