Cap epic-review comments at two per epic

Context

Operator-directed swarm handoff on 2026-06-12: the epic-review substrate must cap structured epic-review comments at two reviews per epic at the very most. The current workflow says the opposite: it keeps per-agent-per-epic one-shot semantics but explicitly encourages independent cross-model reviews and says not to deduplicate.

Release classification: post-release (agent-governance / model-experience substrate cleanup; not a v13.x release blocker).

The Problem

epic-review was designed to prevent one identity from posting repeated full epic reviews on every sub pickup. That solves same-agent repetition but not cross-agent pile-up: as more maintainers and same-family sibling identities join, the current text can turn one epic into a review stack instead of a bounded architectural readback.

The operator correction changes the invariant: cross-model asymmetry remains valuable, but the artifact count must be bounded. After two structured epic-review comments exist on an epic, further agents should cite the existing reviews and proceed with sub-level intake or targeted A2A only when they have a unique blocker/correction. A third full epic-review comment is now wrong-shape substrate noise.

The Architectural Reality

• .agents/skills/epic-review/SKILL.md is a lightweight router; per /create-skill, it should not absorb rule body.
• .agents/skills/epic-review/references/epic-review-workflow.md owns the heavy workflow semantics and currently contains the conflicting rule:
  • line 14: per-agent-per-epic one-shot semantics.
  • line 16: different model identities reviewing the same epic independently is encouraged; two identities means two comments; do not deduplicate.
  • line 171+: subsequent same-identity pickups cite the prior review.
  • line 207: cross-model epic-review is framed as independent complementary value.
• /turn-memory-pre-flight classifies .agents/skills/** changes as skill-loaded memory substrate; the correct placement is the conditional workflow payload, not always-loaded global substrate.

The Fix

Update .agents/skills/epic-review/references/epic-review-workflow.md so the workflow enforces a global cap:

1. Before posting an epic-review comment, count existing structured epic-review comments on the epic.
2. If the count is 0, the first review is allowed.
3. If the count is 1, one additional review may be posted, preserving cross-model/asymmetry value.
4. If the count is >= 2, do not post a third structured epic-review. Cite existing review URLs during sub pickup and use a targeted A2A or narrow issue/PR comment only for a material blocker/correction.
5. Preserve per-agent one-shot semantics inside the global cap: the same identity still cites its prior review rather than re-running.
6. Keep the top-level SKILL.md router unchanged unless a one-line trigger pointer is strictly needed.

Contract Ledger Matrix

Existing-Enforcement Sufficiency Audit

Current enforcement is insufficient. The workflow has no total-review cap and positively encourages cross-model independent comments without deduplication. No mechanical hook or lint currently prevents a third epic-review comment. The minimum sufficient fix for this ticket is therefore the skill workflow rule; mechanical enforcement is out of scope unless recurrence proves it earns a tool-level guard.

Decision Record impact

aligned-with ADR 0008 (skill anatomy / Map-vs-Atlas): this is a payload-level workflow correction for an existing skill, not a new always-loaded rule or ADR amendment.

Acceptance Criteria

• epic-review-workflow.md states a global cap of at most two structured epic-review comments per epic.
• The pre-posting flow instructs agents to count existing structured epic-review comments before creating a new one.
• Cap-full behavior is explicit: cite existing reviews; do not post a third full epic-review; route only unique blockers/corrections through targeted A2A/commentary.
• Same-identity one-shot behavior remains intact and is reconciled with the global cap.
• Cross-model/asymmetry value is preserved but bounded by the cap.
• The top-level epic-review/SKILL.md router is not bloated.
• PR body documents /turn-memory-pre-flight load-effect audit for the skill-substrate change.
• Skill-manifest lint passes or is explicitly N/A because no manifest/router metadata changed.

Out of Scope

• Retroactively deleting or editing prior epic-review comments.
• Building a GitHub bot/hook to mechanically enforce the cap.
• Changing epic-resolution semantics.
• Reducing PR review cross-family requirements; this ticket is only about epic-review comments on epic issues.

Avoided Traps

• Deduplicating all cross-model value away: rejected. The first two reviews preserve asymmetry; the cap prevents pile-up.
• Putting the rule in AGENTS.md: rejected. This is workflow-specific substrate and belongs in the skill payload.
• Treating every later concern as forbidden: rejected. Cap-full agents can still surface unique blockers or corrections, just not as a third full epic-review artifact.

Related

• Skill surface: .agents/skills/epic-review/
• Process references: /create-skill, /turn-memory-pre-flight, ADR 0008.

Live latest-open sweep: checked latest 20 open issues at 2026-06-12T21:03Z; no equivalent cap ticket found. A2A in-flight sweep: recent mailbox contained the operator-directed cap handoff and no competing cap claim.

Origin Session ID: 518c54ce-5871-4ccf-8e88-6ac3b6e16ea8

Retrieval Hint: "epic-review two review cap per epic cross-model dedup operator-directed"