Skip to content

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

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 #1723. Status: ready-for-dev.


QA Lead test-risk inputs (folded in 2026-09-08 — these are ACs, not commentary)

  1. Backward-compatibility must be proven by failure, not by passing. AC4 is satisfiable by a completeness check that skips ingress files. Add negative cases: an ingress with N role-jobs but only N-1 table rows must FAIL completeness, and a row whose asserted Class contradicts the ingress on: block must FAIL the section-3 discriminator check. A completeness rule that cannot fail on an under-documented ingress is not a completeness rule.

Activity

  1. don-petry commented on Sep 13, 2026

    @don-petry
    Collaborator

    Dev-Lead Implementation Plan

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

    Scope

    Extend the §4 classification-table convention and validate-interaction-model.sh so an agent-ingress.yml contributes ONE classification row per collapsed role-job (matched job-by-job against the file's jobs: block), while single-role stubs and carve-outs keep exactly one row — proven backward-compatible by negative (must-fail) fixtures.

    Implementation Checklist

    • Extend §4 shape in docs/agentic-interaction-model.md: document the ingress convention (one row per role-job; first cell = `path` (job-name)) in §4 and update §10's completeness wording (per-job completeness for the ingress file; single-row for everything else).
    • scripts/validate-interaction-model.sh: parse an optional role qualifier from the row's first cell (imv_table_rows → 4th field); add imv_wf_jobs (pure awk job-name extractor); rewrite imv_v_completeness so the ingress file (agent-ingress.yml) requires the row-role set to equal its job set (FAIL[a] for an under-documented job, FAIL[table] for a stale role row), and regular workflows keep the existing exactly-one-row rule. Update the 4-field readers in imv_v_timer_roles / imv_v_class.

    Tests to Write

    Test Command

    bats tests/test_validate_interaction_model.bats (full suite), then bash .dev-lead/scripts/dev-lead-lint.sh

  2. don-petry commented on Sep 13, 2026

    @don-petry
    Collaborator

    Dev-Lead: Progress (in progress — not yet durable)

    Provisional. Nothing is pushed yet; the automation posts the authoritative
    completion record (with PR number + head SHA) after the push. Treat the notes
    below as intent, not delivered results.

    Plan Execution (intended)

    • Extended the §4 shape doc-first (normative source), then the validator and its fixtures.
    • Followed the ADR-0007 ingress convention already used by caller_stub_freeze / validate-ingress-if (key on agent-ingress.yml; one job per collapsed role).

    Files touched (this workspace, not yet pushed)

    • docs/agentic-interaction-model.md: §4 now documents the multi-role ingress convention (first cell `path` (job-name); one row per role-job; carve-outs/legacy stubs keep exactly one row). §10 completeness reworded to per-role-job for the ingress, exactly-one for regular files.
    • scripts/validate-interaction-model.sh: imv_table_rows parses an optional role qualifier (4th field); new pure imv_wf_jobs; imv_v_completeness is ingress-aware — the ingress file's row role-set must equal its jobs: set (under-documented job → FAIL[a]; stale role row → FAIL[table]); regular files keep exactly-one-row. Each per-role row is still class-checked against the shared on: union.
    • tests/test_validate_interaction_model.bats + three new fixture trees under tests/fixtures/interaction-model/ (ingress-pass, ingress-underdoc, ingress-misclass).

    Local checks (provisional — not the pushed run)

    • bats tests/test_validate_interaction_model.bats green locally (incl. the multi-role pass, the N-1-rows must-fail, and the class-contradiction must-fail negatives; the live-repo-passes guard stays green).
    • bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck + profile frontmatter) clean.

    Notes

  3. don-petry commented on Sep 13, 2026

    @don-petry
    Collaborator

    Dev-Lead: Implementation Complete — PR #1794

    The implementation for issue #1728 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.

    Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.

  4. added a commit that references this issue on Sep 22, 2026
  5. added a commit that references this issue on Sep 29, 2026
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

    dev-leadFor dev-lead agent pickupinitiativeEpic / initiative tracking issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions