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://823c6d9f-site.fullsend-ai.workers.dev

Commit: 65e088f301de7847089cd8c9830250cddd3fb9f1

[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.

[rh-hemartin]

/fs-fix do not use a checklist format.

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 7:33 AM UTC · Completed 7:37 AM UTC
Commit: 1dbe7bd · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Replaced checklist format with plain bullet points per human instruction. All - [ ] items converted to - and intro text updated. Matches the formatting convention used by other docs/contributing/ guides.

Fixed (1):

1. do not use a checklist format: Converted all 27 - [ ] checkbox items to plain - bullet points throughout docs/contributing/ci-workflows.md, and updated the intro text from 'Use this checklist when' to 'Follow these conventions when' to match the style used by other contributing guides in the repo

Tests: passed

_{Updated by fullsend fix agent}

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 7:50 AM UTC · Completed 8:01 AM UTC
Commit: 65e088f · View workflow run →

[fullsend-ai-retro]

Retro: PR #5523 — CI workflow conventions guide

Workflow: Issue #5521 (filed by retro agent from PR #5482) → triage → code → PR #5523 → review → human fix request → fix → human approval → merged.

What went well:

• End-to-end pipeline from retro-filed issue to merged PR worked smoothly. Triage, code, and review agents ran without failures.
• The review agent correctly identified a factual inaccuracy: the doc's blanket rule to use ${{ github.workflow }} is wrong for reusable workflows where github.workflow resolves to the caller's name. This was verified against the repo's 7 reusable workflows, all of which use hardcoded prefixes.
• The fix agent was efficient and precisely scoped ($1.10, single iteration, 2-minute agent runtime). It changed only what was asked.

What needed rework:

• The triage agent recommended "structured checklists (not prose)" format. The code agent followed this literally, producing 27 - [ ] checkbox items. Every other doc in docs/contributing/ uses plain - bullets. The human caught this and triggered /fs-fix do not use a checklist format, adding one rework cycle (~6 min wall-clock).
• The review agent missed the formatting inconsistency the human caught. It focused on semantic/technical accuracy but did not compare the new doc's style against peer files in the same directory.

Unresolved finding merged:

• The review agent's medium finding about github.workflow in reusable workflows was not addressed before merge. The doc now contains an inaccuracy that could mislead contributors writing or modifying reusable workflows.

Existing issues with new evidence:

• fullsend#4956, #2099, #870: This PR is another instance of valid medium-severity review findings being merged unaddressed. The review agent correctly flagged the github.workflow reusable-workflow issue but neither the fix agent nor the human resolved it.
• fullsend#3514: The fix agent processed only the human's formatting request and did not address the review agent's open findings — consistent with the gap described in Fix agent should process human reviewer inline comments alongside review agent findings #3514.

Proposals filed

• Code agent should match peer-file formatting when creating new docs (in fullsend-ai/agents)
• Fix ci-workflows.md: add reusable workflow carve-out for github.workflow (in fullsend-ai/fullsend)