Agent Teams: wake/idle message-ordering hardening — disk-first re-read, boundary-drain, one-redundant-confirm (v4.4.52)#1089
Conversation
…disk-first re-read, counter-confirm suppression, boundary-drain rule; fix stale no-hook claims
…ordering hardening — crossed-wake one-redundant-confirm rule, directive-reflection check, no-hook non-goal; fix stale 4-point/no-hook claims (SSOT mirrored)
…ule — post-wake/live-wait idles are delivery-ordering artifacts, not stalls (SSOT mirrored)
…ing surfaces
53 pins across the 5 instruction surfaces (+ the byte-mirrored pact-protocols regions as their own reader-facing surface): line-anchored heading pins, whitespace-normalized rule-phrase pins (robust to hard-wrap and same-line-rider renderings), literal anchor-slug cross-ref pins with slug-derivation integrity checks, and a retired-token absence guard. Presence pins only — no new lockstep counts. Counter-tested against the pre-hardening text: {45 failed, 8 passed}, cardinality recorded in the module.
There was a problem hiding this comment.
Pull request overview
Hardens the PACT “Agent Teams” instruction surfaces against wake/idle message-ordering races by adding seam-agnostic guidance for disk-first state re-reads on wake, boundary-time inbox draining, and lead-side “one redundant confirm then stop” handling. This is primarily documentation/protocol clarification plus a new pin-test module to prevent drift across the reader-facing markdown surfaces, along with a patch version bump to 4.4.52.
Changes:
- Add teammate-side rules (disk-first re-read on wake, counter-confirm suppression, boundary-drain) to
pact-agent-teamsskill docs. - Add lead-side rules (crossed-wake idle handling; directive-reflection check) to completion authority surfaces and orchestrator persona docs; align stall-detection guidance accordingly.
- Introduce
test_wake_ordering_pinned.pystructural pin tests to keep headings/phrases/cross-refs stable across doc surfaces; bump version references to 4.4.52.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates example plugin-cache path version to 4.4.52. |
| pact-plugin/README.md | Bumps displayed plugin version to 4.4.52. |
| pact-plugin/.claude-plugin/plugin.json | Bumps plugin manifest version to 4.4.52. |
| .claude-plugin/marketplace.json | Bumps marketplace metadata version to 4.4.52. |
| pact-plugin/skills/pact-agent-teams/SKILL.md | Adds teammate-side boundary-drain, counter-confirm suppression, and disk-first re-read rules. |
| pact-plugin/protocols/pact-completion-authority.md | Adds lead-side crossed-wake idle handling and directive-reflection check guidance. |
| pact-plugin/protocols/pact-protocols.md | Mirrors the completion-authority additions and updates stall-detection guidance in the SSOT. |
| pact-plugin/protocols/pact-agent-stall.md | Updates stall-detection rule to exempt plausible crossed-wake / intentional-wait idles. |
| pact-plugin/agents/pact-orchestrator.md | Updates persona guidance for crossed-wake and directive-reflection checks; updates read-trigger summary. |
| pact-plugin/tests/test_wake_ordering_pinned.py | Adds pin tests for headings/phrases/cross-refs and retired-token absence across doc surfaces. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Use the Read tool**, not a piped Bash command — Bash permission patterns on | ||
| `~/.claude/` paths are fragile (see §Bash Commands in ~/.claude/ Paths). The file | ||
| is a JSON list of pending messages (`from`, `text`, `summary`, `timestamp`); an | ||
| empty list means nothing is awaiting delivery to you. |
| def _github_slug(heading: str) -> str: | ||
| """GitHub-flavored-markdown anchor slug for a heading line: strip the | ||
| leading hashes, lowercase, drop everything but alphanumerics, spaces, | ||
| and hyphens, then hyphenate spaces.""" | ||
| text = heading.lstrip("#").strip().lower() | ||
| kept = "".join(ch for ch in text if ch.isalnum() or ch in " -") | ||
| return "#" + kept.replace(" ", "-") |
…; narrow non-goal lead-in to synchronous detection
…to HANDOFF notify template
…and heading matchers
8 phrase pins close the run-verified coverage gaps (counter-confirm body, directive-reflection operative sentence per-surface-cased, drain read-only mechanics, single-empty-read rule home, on-wake crossed-directive point). Cross-ref slug pins gain a terminator guard against prefix-engulfment; heading pins now ignore fenced code blocks. Pre-fix flip-set re-measured {53 RED, 8 GREEN}; matcher-robustness probes recorded in the module.
…directive-reflection
…uppression exception
|
Copilot review disposition (both findings evaluated against HEAD):
|
Summary
Hardens the Agent Teams instruction surfaces against wake/idle message-ordering races (crossed-wake idles, stale counter-confirms, mid-turn directive misses). Instruction-only — no hooks, no protocol-shape changes; synchronous wake/send detection remains dead-by-construction (unhookable SendMessage + async-on-delivery inbox writes), so the fix makes agents behave correctly under the race.
Closes #1081. Follow-up filed: #1088 (pre-existing dangling
#meta-blockanchor, out of scope).What landed (5 commits)
skills/pact-agent-teams/SKILL.md— teammate-side: seam-agnostic On-Wake Disk-First Re-Read (anyintentional_waitreason + any crossed inbound directive, per the issue comment's generalized trigger), Counter-Confirm Suppression (complement, not substitute), Boundary-Drain Rule (mandatory literal inbox-file read before every protocol-boundary message, best-effort/fail-open, idempotent reconciliation, REQUIRED drain statement); fixes stale no-hook claims.protocols/pact-completion-authority.md+protocols/pact-protocols.md(byte-identical SSOT mirror) +agents/pact-orchestrator.md— lead-side: Crossed-Wake Idles: One Redundant Confirm, Then Stop (incl. the behavioral no-hook non-goal note), Directive-Reflection Check (delivery ≠ processing); corrects the stale 4-point-rule summary down to the protocol's 3-point rule (retired token dropped) and stale no-consumer claims.protocols/pact-agent-stall.md+ SSOT twin — harmonizes "treat as stalled immediately" with the new rule: post-wake / live-intentional_waitidles are delivery-ordering artifacts, not stalls.tests/test_wake_ordering_pinned.py— 53 presence pins (line-anchored headings, whitespace-normalized phrases robust to rider/wrap renderings, anchor-slug cross-ref + slug-derivation integrity checks, retired-token absence guards). Counter-tested against pre-hardening text: 45/45 revert-couplable pins flipped RED.Why
Live evidence from two orchestration sessions (6+ crossed-wake incidents across three seam types, 5 stale counter-confirms, 1 mid-turn directive miss). The rules were dogfooded during their own implementation: the coder's boundary-drain caught a crossed lead confirm mid-turn and reconciled it idempotently — first in-situ field validation.
Verification
verify-protocol-extracts.sh19/19 MATCH (mirrors byte-identical by construction — same Edit pair applied to both sides)..github/workflows/tests.yml): 10430 collected, 0 failed, 0 errors (explicit errors-token scan).git diffground truth).