[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

Story

As a maintainer defining how agentic roles interact,
I want a single codified standard that states the event-first principle, the three trigger classes and their rules, the GITHUB_TOKEN event-boundary rule with its sanctioned bridges, and the timer contract,
so that the interaction pattern becomes explicit, reviewable, and the normative source that later phases (contracts, CI enforcement, leak fixes) reference instead of tribal knowledge.

Acceptance Criteria

1. A new file docs/agentic-interaction-model.md exists, structured repo-local first but shaped for later promotion into an org standards/agent-standards.md.
2. It defines the event-first principle and the three trigger classes (Class 1 event-driven reactions, Class 2 backstop/reconciliation timers, Class 3 scheduled-origin work) with the rule for each, and classifies the current agentic workflows into those classes.
3. It states the GITHUB_TOKEN event-boundary rule (a GITHUB_TOKEN workflow cannot emit webhooks that trigger other workflows) and enumerates the sanctioned bridges: PAT-backed repository_dispatch (event-preserving) or a stop-condition-gated backstop timer.
4. It defines the timer contract: a timer_role taxonomy (e.g. backstop | safety-net | self-heal), stop-condition-before-acting, idempotency, skipping human-gated markers, and never re-arming a runaway.
5. It encodes the feat: implement issue #846 — [Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #860 postmortem learnings as normative rules (an agent must never be triggered by its own output; a cap whose reset is reachable by the runaway is not a cap; bound the PR not just each worker; count actions not just failures; a new SHA is not new intent; re-trigger crons must check a stop condition; detection must be pushed).
6. It fixes the per-role interaction-contract schema decision (fields and file location) that Story 2 will implement, recording the persona.yml-vs-standalone choice and its cross-repo schema implication.
7. It records the explicit cost/run-count bound: no new count-based breakers; the existing pr-automation-budget (10) + runaway detector remain the ceiling.

Tasks / Subtasks

• Draft docs/agentic-interaction-model.md with sections: event-first principle; the three trigger classes + per-class rules + a classification table of current workflows; the GITHUB_TOKEN boundary rule + sanctioned bridges; the timer contract; the feat: implement issue #846 — [Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #860 normative rules; the interaction-contract schema decision; the cost/run-count bound. (AC: test issue from agent #1, Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3, Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5, feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6, Workflow should skip no-op PRs in MAX_PRS count #7)
• Classify each existing agentic workflow into a trigger class (Class 1: dev-lead, pr-review-trigger, ci-failure-analyst, dismiss-stale-bot-reviews, mention routers, issue-triage-runner; Class 2: pr-review-sweep, dev-lead-retry, initiative-driver; Class 3: token-report, reviewer-report, daily-pr-review-health, -canary, feature-ideation, readme-refresh, standards-sync, idea-triage) by reading .github/workflows/.yml and citing each. (AC: Go-live improvements for PR review agent #2)
• Specify the timer_role taxonomy and the stop-condition/idempotent/human-marker requirements, cross-referencing the existing correct example (initiative-driver's 6 h safety-net) and the leak (dev-lead-retry's 2 h de-facto convergence clock). (AC: Optimize review: small-PR and incremental fast paths #4, feat: add Copilot engine support via REVIEW_ENGINE toggle #5)
• Define the interaction-contract shape (triggers.events[], triggers.timers[] with cron+role+justification+stop_condition+event_fast_path, emits[], idempotency_key, concurrency_lane, stop_markers[], budget) and the file-location decision, noting that extending persona.yml depends on the external persona.schema.json permitting the fields. (AC: feat: feature ideation framework — adversarial proposer/challenger/synthesizer #6)

Dev Notes

• This is a docs-only story; no workflow/script behaviour changes. The implementer sees only this story, so ground the standard in the actual repo trigger inventory (.github/workflows/*.yml) and the postmortem.
• The GITHUB_TOKEN recursion guard is already called out in .github/workflows/actions-fleet-monitor.yml; the sanctioned check_run→fix-ci bridge is implemented by scripts/dev-lead-ci-relay.sh (resolves the PR from a check_run and relays via PAT repository_dispatch) — cite these as the canonical bridge examples.
• The feat: implement issue #846 — [Phase 2] Cache the LSP index and enforce the 30s cold-start SLA with auto-skip #860 learnings are enumerated verbatim in docs/postmortems/2026-06-pr-860-runaway.md ("Learnings" section) — lift them as normative rules, do not paraphrase loosely.
• The timer contract must mirror the language already in AGENTS.md "Scheduled workflows" (off-peak, idempotent/self-healing sweeps) so the two standards are consistent, not contradictory.
• The contract-location decision has a real cross-repo consequence: personas/validate-personas.py fetches persona.schema.json from petry-projects/.github; adding fields to persona.yml requires that schema to allow them. Record this so Story 2 sequences correctly (see epic untracked_prerequisites).
• Testing standard: docs-only, so no bats. A markdown lint / link check is sufficient; the enforceable half lands in Story 4 (validate-interaction-model).

Project Structure Notes

New top-level doc under docs/ alongside docs/postmortems/ and docs/initiatives/. It is the normative anchor the per-role contracts (Story 2), the CI validator (Story 4), and the documentation wiring (Story 7) all reference.

References

• docs/postmortems/2026-06-pr-860-runaway.md
• AGENTS.md#scheduled-workflows
• .github/workflows/actions-fleet-monitor.yml
• scripts/dev-lead-ci-relay.sh
• .github/workflows/dev-lead-retry.yml
• .github/workflows/pr-review-sweep.yml
• .github/workflows/initiative-driver.yml
• personas/validate-personas.py

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

Enhancements from QA Lead review (test-architect advisory, epic #1402)

Folded in from the QA Lead (BMAD Test Architect) advisory on epic #1402. Rationale: a docs AC of "the file exists" is not a test, and the workflow-classification table is the one part of this document that can silently go stale as workflows change.

Additional Acceptance Criteria

8. The trigger-class classification table is authored in a machine-checkable form — each row carries the workflow's path and its asserted trigger class in a stable, parseable shape (e.g. a fixed-column markdown table or a fenced data block) rather than free prose, so Story [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406's validator can verify each row against that workflow's actual on: block.
9. The document states explicitly that the classification table is CI-verified, not review-verified, and names validate-interaction-model ([Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406) as its enforcing check — so a future contributor knows the table is load-bearing and not decorative.

Additional Tasks / Subtasks

• Author the classification table in a parseable shape (stable columns: workflow path | trigger class | timer_role if any | justification) and document that shape in the doc itself, so the validator has a contract to parse against. (AC: Add Claude Code workflow #8)
• Add a short "How this document is enforced" section naming the validate-interaction-model check and what it verifies (classification rows vs. real on: blocks). (AC: feat: inline Claude Code workflow to access repo secrets directly #9)

Dev Notes addendum

• Coordinate the table's exact shape with [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406 — that story parses it. Fix the shape here (this story is the normative source); [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406 consumes it. If the shape changes, [Phase 3] Add scripts/validate-interaction-model.sh + bats, wired into lint.yml as a PR-triggered check #1406's fixtures change with it.