docs(#5521): add CI workflow conventions guide

[fullsend-ai-coder]

Summary

Add docs/contributing/ci-workflows.md to document CI workflow conventions that currently exist only as tribal knowledge. Register it in the AGENTS.md topic-specific guidance table so the review agent references these conventions when reviewing .github/workflows/ changes.

Related Issue

Closes #5521

Changes

• Create docs/contributing/ci-workflows.md covering all 5 convention areas from the issue:
  • Concurrency group pattern (use ${{ github.workflow }}, avoid redundant hardcoded prefixes)
  • Timeout policy (every non-reusable job must set timeout-minutes)
  • Trigger completeness (merge_group: on path-filtered workflows with path-relevance guard)
  • Checkout SHA pinning (current pin documented, pinact for verification)
  • Reusable workflow contracts (document inputs, outputs, check callers on changes)
• Add two bonus sections: Permissions (least-privilege per job) and Additional conventions (self-include in paths, pinned runner version, no hardcoded secrets)
• Uses checklist format throughout for reliable agent consumption (per triage recommendation)
• All examples derived from actual repo workflows (e2e.yml, functional-tests.yml, mint-cf-worker-test.yml)
• Add AGENTS.md table row: CI Workflows | Adding or modifying GitHub Actions workflows under .github/workflows/

Testing

• make lint-md-links passes — all links in new doc resolve
• VitePress sidebar auto-discovers docs/contributing/ via getMarkdownFiles() — no manual config needed
• gitlint passes on commit message

Checklist

• PR title follows Conventional Commits (correct type, ! for breaking changes)
• Commits are signed off (DCO) — human and human-directed agent sessions only
• I wrote this contribution myself and can explain all changes in it

---

Closes #5521

Post-script verification

• Branch is not main/master (agent/5521-ci-workflow-conventions)
• Secret scan passed (gitleaks — 054111862bdd61201a722bc4c28f3fa0c382bdcf..HEAD)
• PR body secret scan passed (gitleaks — no-git)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:14 AM UTC · Completed 10:30 AM UTC
Commit: 1dbe7bd · View workflow run →

[github-actions]

Site preview

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

Commit: 1dbe7bdcf1201b3cd74a1ddf16d4e59bcf40e489

[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

• [API behavior claim] docs/contributing/ci-workflows.md:7 — The concurrency groups section states “Use ${{ github.workflow }} as the workflow identifier — never duplicate the workflow name as a hardcoded string prefix” as a blanket rule. However, in reusable workflows (on: workflow_call), github.workflow resolves to the caller’s workflow name, not the reusable workflow’s own name. This means using github.workflow in a reusable workflow’s concurrency group would produce incorrect scoping — multiple different reusable workflows called from the same caller would share a concurrency group and cancel each other. The repo’s reusable workflows (reusable-code.yml, reusable-review.yml, reusable-triage.yml, reusable-retro.yml, reusable-prioritize.yml, reusable-fix.yml, reusable-dispatch.yml) all correctly use hardcoded role-specific prefixes such as fullsend-code-agent-. The document needs a carve-out or clarification that this rule applies only to non-reusable (top-level) workflows.
  Remediation: Add an exception note to the concurrency groups section, e.g.: “Exception: reusable workflows (on: workflow_call) must use a hardcoded role-specific prefix instead of ${{ github.workflow }}, because github.workflow resolves to the caller’s name in workflow_call context, not the reusable workflow’s own name.”

• [protected-path] AGENTS.md — AGENTS.md is a protected governance file. The PR adds a table entry for the new CI Workflows doc. The change is authorized by issue Add CI workflow conventions doc to close review knowledge gap #5521 and the PR description explains the rationale. Human approval is required for all protected-path changes.

Low

• [edge-case] docs/contributing/ci-workflows.md:17 — The pull_request_target concurrency example omits cancel-in-progress entirely, which defaults to false. The repo’s actual pull_request_target workflows (e2e.yml, functional-tests.yml) use a sophisticated cancel-in-progress expression that gates cancellation on event type and label. A reader following the documented example would not get cancellation behavior for superseded PR runs.

---

Labels: PR adds CI workflow conventions documentation under docs/contributing/ and registers it in AGENTS.md

[fullsend-ai-review]

See the review comment for full details.

[fullsend-ai-review]

[medium] API behavior claim

The concurrency groups section states 'Use ${{ github.workflow }} as the workflow identifier' as a blanket rule. In reusable workflows (on: workflow_call), github.workflow resolves to the caller's workflow name, not the reusable workflow's own name. Multiple different reusable workflows called from the same caller would share a concurrency group and cancel each other. The repo's 7 reusable workflows all correctly use hardcoded role-specific prefixes (e.g., fullsend-code-agent-). The document needs a carve-out for reusable workflows.

Suggested fix: Add an exception note: reusable workflows (on: workflow_call) must use a hardcoded role-specific prefix instead of github.workflow, because github.workflow resolves to the caller's name in workflow_call context.

[fullsend-ai-review]

[medium] protected-path

AGENTS.md is a protected governance file. The PR adds a table entry for the new CI Workflows doc. The change is authorized by issue #5521 and the PR description explains the rationale. Human approval is required for all protected-path changes.

[fullsend-ai-review]

[low] edge-case

The pull_request_target concurrency example omits cancel-in-progress entirely, defaulting to false. The repo's actual pull_request_target workflows (e2e.yml, functional-tests.yml) use a sophisticated cancel-in-progress expression gating on event type and label. A reader following the documented example would not get cancellation behavior for superseded PR runs.