docs(#5402): add normalized-event guidance for BT feature authors

[fullsend-ai-coder]

Summary

Add normalized-event schema reference to AGENTS.md so code and review agents use correct CEL transition kinds in BT feature files, preventing silent filter mismatches like the synchronize vs synchronized bug caught in PR #5309.

Related Issue

Fixes #5402

Changes

• Add "Behaviour-test feature files and CEL triggers" section to AGENTS.md after the forge abstraction section
• Include transition kind vocabulary table mapping normalized kinds to raw GitHub webhook action names
• Call out the synchronize → synchronized pitfall explicitly
• Document label_changed trigger pattern for ADR 0054 auth compliance in BT scenarios
• Add review guidance to flag raw webhook action names in CEL expressions

Testing

• scan-secrets passes on changed file
• gitlint passes on commit message
• make lint — pre-commit could not run in sandbox (network restriction); post-script runs authoritatively

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Documentation-only change — no code or test changes required

---

Closes #5402

Post-script verification

• Branch is not main/master (agent/5402-agents-cel-event-guidance)
• Secret scan passed (gitleaks — d9185cb4c47c583de659ff76e15a7ba167899d3a..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:25 AM UTC · Completed 9:38 AM UTC
Commit: fb75bae · View workflow run →

[github-actions]

Site preview

Preview: https://c26d839a-site.fullsend-ai.workers.dev

Commit: fb75baed29acc40dcb633967e625e73fe750558d

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Medium

• [incomplete-vocabulary] AGENTS.md:106 — The transition kind vocabulary table omits updated, a valid value in the transition.kind enum defined in the normative schema (normalized-event.schema.json) and documented in the normative README as "Legacy umbrella; prefer edited or synchronized for new adapters." While the section links to the normative README as source of truth, the table header "Transition kind vocabulary" implies completeness, and omitting a valid enum value could confuse authors who encounter updated in existing adapter output or fixtures.
  Remediation: Add a row for updated with a note such as: updated | (various) | Legacy umbrella — prefer edited or synchronized for new triggers.

• [review-guidance-completeness] AGENTS.md:139 — The "When reviewing BT feature files" subsection instructs reviewers to flag CEL expressions using raw webhook names but does not specify a severity level. Both comparable "When reviewing" guidance blocks in AGENTS.md include explicit severity levels (line 74: "medium-severity finding"; line 92: "medium-severity or higher finding"). Omitting the severity classification creates inconsistent review guidance.
  Remediation: Add a severity level, e.g., "Flag ... as a medium-severity finding."

• [protected-path] AGENTS.md — AGENTS.md is a protected path requiring human approval. The PR has a linked issue (AGENTS.md: add normalized-event schema reference for BT feature file authors #5402) and explains the rationale (preventing CEL constant typos like the synchronize/synchronized bug in PR test(#5206): add fork dispatch feature file, cleanup, and docs #5309). Human approval is always required for protected-path changes, regardless of context.

Low

• [organizational-consistency] AGENTS.md:96 — The new section uses ### subsections, which differs from its immediate neighbors ("Forge abstraction" and "Architecture Decision Records") that use bold-prefixed paragraphs. However, this pattern is used elsewhere in the document ("Go code," "Shell scripting"), so it is not unprecedented.

---

Labels: PR adds documentation guidance for BT feature files and CEL triggers to AGENTS.md

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] incomplete-vocabulary

The transition kind vocabulary table omits updated, a valid value in the transition.kind enum defined in the normative schema (normalized-event.schema.json) and documented in the normative README as "Legacy umbrella; prefer edited or synchronized for new adapters." While the section links to the normative README as source of truth, the table header "Transition kind vocabulary" implies completeness, and omitting a valid enum value could confuse authors who encounter updated in existing adapter output or fixtures.

Suggested fix: Add a row for updated with a note such as: updated | (various) | Legacy umbrella — prefer edited or synchronized for new triggers.

[fullsend-ai-review]

[medium] review-guidance-completeness

The "When reviewing BT feature files" subsection instructs reviewers to flag CEL expressions using raw webhook names but does not specify a severity level. Both comparable "When reviewing" guidance blocks in AGENTS.md include explicit severity levels (line 74: "medium-severity finding"; line 92: "medium-severity or higher finding"). Omitting the severity classification creates inconsistent review guidance.

Suggested fix: Add a severity level, e.g., "Flag ... as a medium-severity finding."

[fullsend-ai-review]

[low] organizational-consistency

The new section uses ### subsections, which differs from its immediate neighbors ("Forge abstraction" and "Architecture Decision Records") that use bold-prefixed paragraphs. However, this pattern is used elsewhere in the document ("Go code," "Shell scripting"), so it is not unprecedented.