Repository navigation
[Phase 2] Teach the interaction-model section 4 table and validate-interaction-model about a multi-role ingress file #1721
Description
Story
As a interaction-model maintainer,
I want extend the section 4 classification-table shape and validate-interaction-model so one agent-ingress.yml maps to MULTIPLE classified roles (its per-job roles) instead of the current exactly-one-row-per-workflow completeness rule,
so that collapsing event-driven roles into one file doesn't fail the CI-verified completeness check, and each collapsed role still classifies against the ingress on: block.
Acceptance Criteria
- The section 4 table shape in docs/agentic-interaction-model.md is extended so agent-ingress.yml contributes ONE classification row per collapsed role/job (not exactly one row for the file). The normative shape change is made HERE first (section 10: shape changes here, fixtures follow -- never the reverse).
- validate-interaction-model.sh's completeness check (today: every in-scope workflow has exactly one row) is updated so an ingress file with N role-jobs satisfies completeness with N rows, and each row's asserted Class is still checked against the ingress
on:block via the section 3 discriminator. - Carve-out workflows (pull_request_target stubs, Class-2/3 timers) keep their own single rows unchanged.
- Backward-compatible with pre-collapse single-role stubs (each still classifies as exactly one row).
- bats/fixture coverage for a multi-role ingress classification (each job's Class verified against the shared on: block; completeness passes with N rows).
Tasks / Subtasks
- Extend the section 4 table shape in docs/agentic-interaction-model.md to allow one row per role-job of an ingress file; document the convention. (AC: test issue from agent #1)
- Update validate-interaction-model.sh completeness + class-vs-on: checks to handle N rows per ingress file via the section 3 discriminator. (AC: Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3)
- Preserve single-row handling for legacy per-role stubs and carve-outs. (AC: Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4)
- Add a multi-role ingress fixture + assertions to the validator's bats. (AC: feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
Dev Notes
- Section 4 (docs/agentic-interaction-model.md L155-236) is a FIXED-COLUMN, CI-verified table:
Workflow (path) | Class | timer_role | Justification. Section 10 (L513-539) states the completeness check is BIDIRECTIONAL -- every in-scope.github/workflows/*.ymlnot on the exclusion list must have EXACTLY ONE row, and a workflow absent from both table and exclusion list fails. Collapsing dev-lead + pr-review-mention (both currently their own Class-1 rows, L174/L179) into agent-ingress.yml breaks 'exactly one row per file' -- the rule must become 'exactly one row per classified role', with the ingress file contributing N. - The validator is
validate-interaction-model/ [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406 (interaction-model section 10). The section 3 discriminator parses theon:block to assert Class; for an ingress file all jobs share ONEon:block (the union), so each per-role row is checked against that same union -- the validator must map a row to its job's subset of triggers via the jobif:event filter (Story 1/2) rather than expecting a distinct per-fileon:. - Normative-source rule (section 10 L537-539): the table's shape is fixed in THIS document; [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406 consumes it. Change the doc shape FIRST, then the validator fixtures -- never the reverse.
- Carve-outs stay one-row: add-to-project.yml / dependabot-* keep their pull_request_target rows; the section 4 exclusion list (L210-236) already lists the thin-caller carve-outs -- do not move them.
- Testing (ADR-0004): extend the validate-interaction-model bats/fixtures with a multi-role ingress case and a legacy single-role case to prove backward-compat.
Project Structure Notes
Edits docs/agentic-interaction-model.md (section 4 shape) + scripts/validate-interaction-model.sh + its bats/fixtures. No reusable/trigger change. This is an in-repo gate that would fail on Story 6's collapse, so it must land first.
References
- docs/agentic-interaction-model.md#4-classification
- docs/agentic-interaction-model.md#10-enforcement
- docs/agentic-interaction-model.md#3-discriminator
- scripts/validate-interaction-model.sh
- open_epics: Formalize the agentic PR-interaction model (event-first, timers-as-backstop) — clear, repeatable, enforceable #1402 (formalize the agentic interaction model)
Likely target surface
docs/agentic-interaction-model.mdscripts/validate-interaction-model.shtests/ (validate-interaction-model fixtures)
Story prepared by the BMAD Scrum Master (Bob) for epic #1716. Status: ready-for-dev.
Activity
github-actions commentedon Sep 8, 2026
Superseded by the re-planned initiative epic #1723 (re-planned from idea discussion #1711).