feat: implement issue #1403 — [Phase 1] Write docs/agentic-interaction-model.md — the event-first standard, three trigger classes, the GITHUB_TOKEN bridge rule, and the timer contract - #1413
Conversation
…n-model.md — the event-first standard, three trigger classes, the GITHUB_TOKEN bridge rule, and the timer contract
🤖 CodeAnt AI — Review Status
|
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Warning Review limit reached
Next review available in: 51 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
codeant-ai
Bot
added
the
size:L
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new normative document, docs/agentic-interaction-model.md, which codifies the triggering and interaction patterns of agentic roles to prevent runaway loops and ensure consistent event-driven behavior. The feedback suggests enhancing the documentation regarding Personal Access Tokens (PATs) by noting that fine-grained PATs are restricted to a single resource owner, and recommending classic PATs or GitHub App installation tokens as alternatives for workflows spanning multiple organizations.
PR Summary by QodoAdd normative agentic interaction model standard (triggers, bridges, timers)
AI Description
Diagram
High-Level Assessment
Files changed (1)
|
Dev-Lead — review-changes (applied)Changes committed and pushed. |
Code Review by Qodo
Context used✅ Compliance rules (platform):
48 rules 1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
don-petry
left a comment
don-petry
left a comment
There was a problem hiding this comment.
Review — PR #1413 (docs/agentic-interaction-model.md, story #1403)
Strong first draft. §3's formal class discriminator is the best part of this document: making Class 1 vs {2,3} derivable from the on: block while Class 2 vs 3 turns on the declared timer_role is exactly right — a timer's role genuinely isn't visible in on:, and stating that as a consistency invariant rather than a derived label is what makes #1406 implementable. §8.2's decision (standalone contract, not persona.yml) is correct and the cross-repo sequencing rationale matches the caller-stub skew rule. §6.3's honest labelling of dev-lead-retry as the leak, and §9's refusal to add new counters, both land well.
Fact-checks passed. I verified several rows against the real on: blocks and they are accurate: pr-review-mention.yml → pull_request:[review_requested] ✅, issue-triage-runner.yml → issues:[opened, reopened] ✅, standards-sync.yml's first-Monday guard ✅ (.github/workflows/standards-sync.yml:28-40). No factual errors found in the rows that exist.
Requesting changes for one substantive gap.
1. (must fix) The §4 table is incomplete, and §10's enforcement is one-directional — so omissions are silent and permanent
§10 specifies the validator as: "Every row of the §4 table is parsed ... and its asserted Class is checked against that workflow's actual on: triggers." That is row → reality. Nothing checks reality → row. A workflow with no row therefore passes CI forever, and a new agentic role can be added with no row at all — which defeats the stated purpose of this initiative ("enforceable as we add more agentic roles").
This is not hypothetical: 13 agentic workflows currently have no row, several heavily agent/LLM-driven:
| Missing workflow | Why it belongs in the table |
|---|---|
actions-fleet-monitor.yml |
This document cites it in §5 as the canonical PAT-bridge example, then omits it from the classification. Internal inconsistency. |
dependency-advisory.yml |
Claude-driven PR advisory that posts "No action required." comments — squarely the no-action noise class this initiative exists to reduce. |
spec-drift.yml |
Advisory agent; posts a comment on the story issue. |
initiative-planner.yml |
The BMAD planner (agent refs: 14) — and it is the discussion:[labeled] → workflow_dispatch bridge, a §5 case worth classifying explicitly. |
gh-aw-cross-org.yml |
repository_dispatch receiver (agent refs: 18). |
stale-manager.yml, docs-health-check.yml, skill-eval-report.yml |
Scheduled agentic (gh-aw) roles — Class 3. |
premature-closure-audit.yml, auto-rebase-health.yml |
Scheduled audits/reports — Class 3. |
auto-rebase-retry.yml |
workflow_run self-heal handler — a Class 1 reaction (and an interesting edge case for the taxonomy: a self-heal reaction, not a self-heal timer). |
pr-auto-review.yml |
workflow_run / check_suite / pull_request_review / pull_request; it was 6 runs/hr in the baseline census, so it is materially part of the interaction surface. |
persona-runner.yml |
The persona runtime (repository_dispatch) — the receiving half of the mention bridge. |
Asks:
- Add rows for the agentic workflows above (or explicitly exclude each, per ask 3).
- Add a completeness rule to §10 — and a matching AC on #1406: every workflow in the agentic set has exactly one row; an agentic workflow with no row fails the check. Bidirectional, not row-only.
- Replace the prose exclusion note under the table with an explicit, enumerable exclusion list. Today it reads "Non-agentic infrastructure workflows (CI, Lint, gate guards ..., dependabot plumbing, thin caller stubs) are out of scope: they are not roles that interact." A validator cannot evaluate "is not a role that interacts" — so as written, completeness is undecidable and ask 2 cannot be implemented. Make it a literal allowlist/denylist (a path list in this doc, or a small data file the validator reads), so "is this workflow in scope?" has a mechanical answer.
Without 2 and 3, the table is CI-verified only for the rows someone remembered to write — which is closer to review-verified than §10 claims.
2. (minor) auto-rebase-retry.yml exposes a taxonomy edge worth one sentence
It is a workflow_run reaction that retries a failed prior run — semantically self-heal, but it is Class 1 (an event reaction), and §6.1 defines self-heal only as a timer_role. Please state explicitly that timer_role applies only to Class 2/3 schedules, and that an event-driven retry handler is plain Class 1 with no timer_role. Otherwise the first implementer to classify it will reasonably guess wrong.
3. (nit) §4's intro says "fixed-column markdown table with exactly these columns"
Worth pinning the separator/escaping convention too (justification cells contain |-free prose and backticked paths today). #1406 has to parse this; one sentence on the escaping rule now prevents a fixture rewrite later.
Nothing here is a disagreement with the model itself — §§1–3 and §§5–9 are sound and I'd merge them as-is. The gap is that §4 + §10 currently under-deliver the "enforceable" half of the story's own title, and that is the half this initiative is for.
|
CI checks on this PR are still running. Once they complete, re-mention Posted by the donpetry-bot PR-review cascade. |
Response to don-petry's reviewAddressed all three asks (must-fix, minor, nit) plus the two qodo-code-review correctness bugs. Must-fix: §4 table completeness + §10 bidirectional enforcement14 missing rows added to §4 (the 13 you listed plus
Prose exclusion note replaced with an explicit two-column path table (20 entries grouped by category: CI infra, tests, gate guards, Dependabot plumbing, thin caller stubs, reusable workflows, manual admin tools). Each row is a resolvable path — the validator now has a mechanical yes/no answer for every §10 completeness rule added as a new bullet under Minor:
|
Dev-Lead — review-changes (applied)Changes committed and pushed. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
don-petry
left a comment
don-petry
left a comment
There was a problem hiding this comment.
Re-review — all findings addressed ✅
Verified the two review-changes commits (d24d319a, 4c9fc396) independently against the branch, not just the response summary.
| Finding | Status | Verification |
|---|---|---|
| 1a — missing rows | ✅ | Table went 20 → 34 rows. All 13 I listed are present, plus release-notes.yml which dev-lead found on its own. |
| 1b — explicit exclusion list | ✅ | Prose note replaced with a 20-row path table, each entry a resolvable path with a category rationale. The scope question now has a mechanical answer. |
| 1c — bidirectional completeness | ✅ | §10 gains a "Completeness (bidirectional)" bullet: every in-scope workflow must have exactly one row; absent from both table and exclusion list = CI failure. The #1406 AC is stated inline. |
2 — timer_role taxonomy edge |
✅ | §6.1 now states timer_role is "exclusively a property of Class 2/3 scheduled workflows", with auto-rebase-retry.yml as the worked example. |
| 3 — separator/escaping convention (nit) | ✅ | §4 now pins it: justification cells must be ` |
Independent invariant check. I verified the document now satisfies the rule it just introduced — the check #1406 will implement:
workflows on branch : 54
covered by doc : 54 (34 classified + 20 excluded)
in neither list : 0 ← full coverage
stale rows : 0 ← no row names a non-existent workflow
Exact 54/54. No gaps, no stale rows. Also confirmed several corrections dev-lead made to my own characterizations were right: spec-drift.yml is pull_request:[closed] (post-merge advisory, not a synchronize reaction), and initiative-planner.yml is workflow_dispatch-only at the stub with the discussion:[labeled] signal arriving via the redispatch bridge.
No further findings. From my side this is ready to merge — I can't post a formal approval because dev-lead authors as don-petry, the same account I review from (see the note below), so treat this as an explicit approve-equivalent.
Process gap this PR surfaced (logging separately, not a blocker here)
I attempted to post this review's predecessor as CHANGES_REQUESTED and GitHub refused: "Can not request changes on your own pull request." dev-lead's declared runtime.identity.account is don-petry — the same account the human owner uses — so the owner structurally cannot use the blocking review path on any dev-lead PR. I fell back to COMMENTED + inline threads, which dev-lead's fix-reviews did enumerate and honor correctly, so the outcome was right; but the mechanically blocking path was unavailable.
This is the review-path sibling of the issue-comment gap that maintainer-comment-gate.sh (#1290) was built to close — that gate exists precisely because dev-lead posts as don-petry and login alone cannot separate agent from maintainer. Worth tracking under epic #1402 since it is squarely an agent-interaction-model concern.
Dev-Lead — review-changes (no-changes)No changes were needed for this PR. |
|
The gate-integrity gap this PR surfaced — the maintainer review threads here were resolved by the agent identity ( |
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: 4c9fc3967cae7eb5c0b041f376a4f4333ba3bea5
Review mode: triage-approved (single reviewer)
Summary
Docs-only PR adding docs/agentic-interaction-model.md (+489, single file): the normative agentic interaction standard for issue #1403. Triage assessment confirmed — LOW risk, all CI green, all review threads resolved, owner posted an approve-equivalent re-review. Independent spot-checks verified the classification table against real on: blocks and confirmed the 54-workflow file set at the PR head is identical to current main (no stale rows despite BEHIND status).
Linked issue analysis
Closes #1403. All 7 acceptance criteria substantively addressed: (1) docs/agentic-interaction-model.md exists, shaped repo-local-first for org promotion; (2) event-first principle + three trigger classes with per-class rules and a 34-row classification table plus a 20-row exclusion list (§1–§4); (3) GITHUB_TOKEN event-boundary rule with the two sanctioned bridges — PAT repository_dispatch and stop-condition-gated backstop timer (§5); (4) timer contract with the backstop|safety-net|self-heal timer_role taxonomy, stop-condition-before-acting, idempotency, human-gate markers, never re-arm (§6); (5) the seven #860 postmortem learnings encoded as normative rules (§7); (6) interaction-contract schema decision fixed — standalone repo-local file, with the persona.yml promotion sequenced behind the org schema change (§8); (7) no new count-based breakers; existing pr-automation-budget (10) + runaway detector remain the ceiling (§9).
Findings
No blocking findings.
- Prior review cycle fully resolved. The owner's must-fix findings (table completeness, machine-checkable exclusion list, bidirectional §10 enforcement), the timer_role taxonomy edge, and the separator/escaping nit were all addressed across commits d24d319/4c9fc396; the owner's re-review verified each and stated approve-equivalent (a formal approval is impossible since dev-lead authors as the same account). All 7 inline review threads are resolved.
- Independent verification (this review): the pr-review-sweep.yml row matches its actual on: block at the PR head (cron 2,17,32,47 + workflow_run fast path); the workflow file set at the PR head is byte-identical to current origin/main — 54 files, zero content diffs — so the table's 54/54 coverage (34 classified + 20 excluded) holds against main today and no rows are stale.
- Secret scan: the run_secret_scanning MCP tool is not available in this environment; the gitleaks CI check passed. Diff is pure markdown documentation — no secrets, no executable code, no workflow changes.
- Non-blocking note: the doc is a point-in-time inventory until the #1406 validator lands; any workflow added/removed on main before then will silently stale the table. That is a known, accepted gap this initiative's Story 4 exists to close.
CI status
All required checks green at 4c9fc39: Lint, ShellCheck, CodeQL (actions + python), unit-tests, guard, holdout-guard, AgentShield, Agent Security Scan, Secret scan (gitleaks), SonarCloud quality gate, Compile agentic workflows — all SUCCESS. Cancelled/skipped entries are superseded duplicate runs and inapplicable ecosystem audits. Mergeable; branch is BEHIND main but with zero conflicting content.
Reviewed automatically by the PR-review agent (single-reviewer mode: fable 5). Reply if you need a human review.
|
|
Advisory bots were rate-limited; auto-approval is withheld until they recover. pr-review-sweep will re-review this PR after 2026-08-02T02:50:38Z. |
2 participants
User description
Closes #1403
Implemented by dev-lead agent. Please review.
CodeAnt-AI Description
Define how agentic workflows are triggered, scheduled, and prevented from entering runaway loops
What Changed
GITHUB_TOKENevent boundary and the approved PAT-based and timer-based ways to bridge itImpact
✅ Fewer agent-triggered runaway loops✅ Clearer event-versus-timer workflow behavior✅ Safer recovery from missed workflow events💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.