Skip to content

[Phase 2] Teach the interaction-model section 4 table and validate-interaction-model about a multi-role ingress file #1721

Closed

Description

@github-actions

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

  1. 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).
  2. 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.
  3. Carve-out workflows (pull_request_target stubs, Class-2/3 timers) keep their own single rows unchanged.
  4. Backward-compatible with pre-collapse single-role stubs (each still classifies as exactly one row).
  5. 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

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/*.yml not 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 the on: block to assert Class; for an ingress file all jobs share ONE on: 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 job if: event filter (Story 1/2) rather than expecting a distinct per-file on:.
  • 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

Likely target surface

  • docs/agentic-interaction-model.md
  • scripts/validate-interaction-model.sh
  • tests/ (validate-interaction-model fixtures)

Story prepared by the BMAD Scrum Master (Bob) for epic #1716. Status: ready-for-dev.

Activity

  1. github-actions commented on Sep 8, 2026

    @github-actions
    ContributorAuthor

    Superseded by the re-planned initiative epic #1723 (re-planned from idea discussion #1711).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    initiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions