[Phase 2] Author a machine-readable interaction contract for every agentic role, per the standard #1404

Activity

1. github-actions

   added a parent issue on Aug 1, 2026

   • Formalize the agentic PR-interaction model (event-first, timers-as-backstop) — clear, repeatable, enforceable #1402
2. github-actions

   added

   initiativeEpic / initiative tracking issueEpic / initiative tracking issue

   on Aug 1, 2026
3. github-actions

   marked this as blocked on Aug 1, 2026

   • [Phase 1] Write docs/agentic-interaction-model.md — the event-first standard, three trigger classes, the GITHUB_TOKEN bridge rule, and the timer contract #1403
4. github-actions

   marked this as blocking 5 issues on Aug 1, 2026

   • [Phase 2] Add the "How to add an agentic role" runbook and a PR-template interaction-contract section #1405
   • [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406
   • [Phase 4] Demote dev-lead-retry from normal-path driver to a true backstop — resume blocked states event-first #1407
   • [Phase 4] Narrow pr-review-sweep's cron scope to genuinely un-eventable cases and surface a sweep-hit-rate metric in daily health #1408
   • [Phase 5] Wire the standard into AGENTS.md and per-agent docs, and reconcile the ci-failure-analyst spec vs deployed divergence #1409
5. don-petry

   unmarked this as blocking 2 issues on Aug 2, 2026

   • [Phase 4] Demote dev-lead-retry from normal-path driver to a true backstop — resume blocked states event-first #1407
   • [Phase 4] Narrow pr-review-sweep's cron scope to genuinely un-eventable cases and surface a sweep-hit-rate metric in daily health #1408
6. don-petry

   added

   dev-leadFor dev-lead agent pickupFor dev-lead agent pickup

   on Aug 2, 2026
7. don-petry commented on Aug 2, 2026

   

   don-petry

   on Aug 2, 2026

   Collaborator

   More actions

   Dev-Lead Implementation Plan

   Issue: #1404 — [Phase 2] Author a machine-readable interaction contract for every agentic role, per the standard

   Scope

   Author a standalone, machine-readable interaction: contract for each of the 11 agentic roles (8 personas + 3 non-persona runtimes) per the schema fixed in docs/agentic-interaction-model.md §8.1, using the standard's §8.2 location decision (option b: standalone repo-local files, not persona.yml) — so there is no cross-repo persona.schema.json dependency and validate-personas.py is untouched — plus a hermetic well-formedness validator + bats test.

   Location decision (per §8.2)

   • Persona contracts (8): personas/<id>/interaction.yml — co-located, standalone (NOT a persona.yml block).
   • Runtime contracts (3): interaction-contracts/{dev-lead,pr-review,ci-failure-analyst}.yml — standalone, keyed by workflow path.

   Trigger cross-check (AC #3 — matched against real on: blocks)

   • dev-lead persona → dev-lead.yml (Class 1: pull_request, pull_request_review, pull_request_review_comment, issue_comment, issues, check_run, repository_dispatch; no schedule).
   • pr-review persona → pr-review-trigger.yml (Class 1: check_suite, pull_request_review, pull_request, workflow_dispatch, repository_dispatch:pr-review-mention).
   • business-analyst / devops-lead / qa-lead / scrum-master / security-lead / sre-lead → persona-mention.yml (Class 1: issue_comment, pull_request_review_comment, discussion_comment) → persona-runner. Contracts declare the deployed router triggers, reconciling the broader-but-not-wired surfaces in persona.yml.
   • dev-lead runtime → dev-lead.yml + dev-lead-retry.yml (Class 2 self-heal cron 15 */2 * * *, event_fast_path: null — the §6.3 leak).
   • pr-review runtime → pr-review-trigger.yml + pr-review-sweep.yml (Class 2 backstop cron 2,17,32,47 * * * *, event_fast_path: workflow_run:[completed]).
   • ci-failure-analyst → ci-failure-analyst.lock.yml (Class 1: check_run:[completed]; byte-frozen ring-0 stub — described, never edited).

   idempotency_key / concurrency_lane sourced from each workflow's real concurrency.group (dev-lead-reusable per-PR/per-issue lanes, pr-review per-PR lane, ci-failure-analyst-${head_sha}, dev-lead-retry, pr-review-sweep-${branch}, persona-runner lane). stop_markers from the human-gate markers in use (needs-human-review, dev-lead:needs-human, <id>:hands-off). budget: pr-automation-budget for write runtimes, none for advisory mention personas.

   Implementation Checklist

   • interaction-contracts/validate-interaction-contracts.py — hermetic (no-network) well-formedness validator: required fields, timer sub-fields, Class-2 timers carry timer_role+stop_condition, emits/events disjointness (narrow §7-rule-1 guard), workflows[] paths exist. Deep on:-block match is Story 4 ([Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406).
   • personas/<id>/interaction.yml × 8
   • interaction-contracts/{dev-lead,pr-review,ci-failure-analyst}.yml × 3
   • .github/workflows/lint.yml — add validate-interaction-contracts job (mirrors validate-personas) + register the new bats file in the bats job list.

   Tests to Write

   • tests/test_validate_interaction_contracts.bats — hermetic, mirrors tests/test_validate_personas.bats: accepts a well-formed fixture; rejects missing required field, malformed timer, Class-2 timer with no timer_role, emit that self-triggers, non-existent workflow path.

   Test Command

   bats tests/test_validate_interaction_contracts.bats (full suite: scripts/run-bats.sh tests/*.bats); lint gate: bash .dev-lead/scripts/dev-lead-lint.sh; contracts checked live via python3 interaction-contracts/validate-interaction-contracts.py.
8. don-petry commented on Aug 2, 2026

   

   don-petry

   on Aug 2, 2026

   Collaborator

   More actions

   Story 2 / #1404 — complete

   Authored a machine-readable interaction contract for every agentic role and wired a hermetic CI gate to keep them honest.

   What shipped

   11 contracts (§8.2 decision: option (b) — standalone repo-local files, so persona.schema.json / validate-personas.py are untouched, no cross-repo dependency):

   • 8 persona lenses — personas/<id>/interaction.yml for dev-lead, pr-review, business-analyst, devops-lead, qa-lead, scrum-master, security-lead, sre-lead.
   • 3 runtime lenses — interaction-contracts/{dev-lead,pr-review,ci-failure-analyst}.yml (deployment view; dev-lead/pr-review fold in their Class-2 backstop timers, ci-failure-analyst has no persona manifest).

   Each contract declares the full §8.1 shape: triggers.events[], triggers.timers[] (cron + role + justification + stop_condition + event_fast_path), emits[], idempotency_key, concurrency_lane, stop_markers[], budget.

   Acceptance criteria

   • AC#1 — every agentic role has a contract (8 personas + 3 runtimes). ✅
   • AC#2 — every declared field present and typed. ✅
   • AC#3 — declared triggers verified against each role's deployed on: block, not aspiration. The advisory personas record only persona-mention.yml's wired issue_comment/pull_request_review_comment/discussion_comment; the broader persona.yml surfaces (reviewer-assignment etc.) are noted as not-yet-wired (finding 10 / Persona framework — pre-rollout review findings .github#755). ✅
   • AC#4 — location matches the §8.2 decision; persona validator dependency respected (no persona.yml extension). ✅
   • AC#5 — hermetic parse/consistency check interaction-contracts/validate-interaction-contracts.py, gated in lint.yml (new validate-interaction-contracts job + tests/test_validate_interaction_contracts.bats registered in the bats job). ✅

   Modeling notes

   • The two flagged §6 timer shapes are captured honestly: pr-review-sweep is a textbook §2 Class-2 backstop (event_fast_path: workflow_run:[completed]); dev-lead-retry is the §6.3 self-heal leak (event_fast_path: null). Both re-dispatches are modeled as the timer's stop-condition-gated mechanism, not free dispatch: emits — so the §7 feat: implement issue #846 — [Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #860 rule-1 self-trigger check stays meaningful without false-positiving legitimate gated backstops.
   • The validator enforces only the well-formedness half of feat: implement issue #846 — [Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #860 rule 1 (a dispatch:X emit must not name a subscribed repository_dispatch:X; no literal event/emit collision). Deep semantic self-trigger analysis is deferred to Story 4 / [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406 as scoped.

   Verification

   • bats tests/test_validate_interaction_contracts.bats → 13/13 pass (TDD: written red before the validator existed).
   • python3 interaction-contracts/validate-interaction-contracts.py . → OK: 11 interaction contract(s) valid, invariants hold.
   • bash .dev-lead/scripts/dev-lead-lint.sh → all checks passed (shellcheck 98 files + agent-profile/CODEOWNERS frontmatter).
   • lint.yml re-validated as YAML after the edits.

   CI owns the commit/PR.
9. don-petry

   added a commit that references this issue on Aug 2, 2026

   feat: implement issue #1404 — [Phase 2] Author a machine-readable int…

   ...

   792817d
10. don-petry

    closed this as completedin #1418on Aug 2, 2026