Repository navigation
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 #1723. Status: ready-for-dev.
QA Lead test-risk inputs (folded in 2026-09-08 — these are ACs, not commentary)
- 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
don-petry commentedon Sep 13, 2026
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.shso anagent-ingress.ymlcontributes ONE classification row per collapsed role-job (matched job-by-job against the file'sjobs:block), while single-role stubs and carve-outs keep exactly one row — proven backward-compatible by negative (must-fail) fixtures.Implementation Checklist
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); addimv_wf_jobs(pure awk job-name extractor); rewriteimv_v_completenessso 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 inimv_v_timer_roles/imv_v_class.Tests to Write
ingress-passfixture: multi-role ingress (2 role-jobs, 2 Class-1 rows, shared no-scheduleon:union) + a legacy single-role stub → passes.ingress-underdocfixture: ingress with N role-jobs but N-1 rows → must FAIL[a] completeness (QA AC feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6).ingress-misclassfixture: an ingress row whose asserted Class contradicts the sharedon:union → must FAIL[class] via the §3 discriminator (QA AC feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6).tests/test_validate_interaction_model.batsfor the three trees + animv_wf_jobsunit test; keep the live-repo-passes test green.Test Command
bats tests/test_validate_interaction_model.bats(full suite), thenbash .dev-lead/scripts/dev-lead-lint.shdon-petry commentedon Sep 13, 2026
Dev-Lead: Progress (in progress — not yet durable)
Plan Execution (intended)
caller_stub_freeze/validate-ingress-if(key onagent-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_rowsparses an optional role qualifier (4th field); new pureimv_wf_jobs;imv_v_completenessis ingress-aware — the ingress file's row role-set must equal itsjobs: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 sharedon:union.tests/test_validate_interaction_model.bats+ three new fixture trees undertests/fixtures/interaction-model/(ingress-pass,ingress-underdoc,ingress-misclass).Local checks (provisional — not the pushed run)
bats tests/test_validate_interaction_model.batsgreen 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
agent-ingress.ymlyet (Story 6 collapse) — this gate lands first, forward-compatible; existing §4 rows and the exclusion list are unchanged (AC3/AC4).don-petry commentedon Sep 13, 2026
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.
3f38f034305f053e4f5e10dbdfc7980b1fc0bdb9Review 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.
feat: implement issue #1728 — [Phase 2] Teach the interaction-model s…
feat: implement issue #1728 — [Phase 2] Teach the interaction-model s…