docs(#4071): broaden workflow sync guidance to cover secret/input threading

[fullsend-ai-coder]

Rename the "Dispatch workflows" section in AGENTS.md to "Workflow contracts" and expand it beyond dispatch-scaffold routing sync. The new guidance documents the general GHA constraint that reusable workflows do not inherit secrets or variables, requiring every caller to explicitly forward them. Both installation-mode chains (per-org and per-repo) are called out, along with the silent failure mode of omitted optional secrets arriving as empty strings. A review instruction is added so agents and contributors flag missing forwarding hops.

Co-Authored-By: Claude Opus 4.6 noreply@anthropic.com

---

Closes #4071

Post-script verification

• Branch is not main/master (agent/4071-broaden-workflow-sync-guidance)
• Secret scan passed (gitleaks — 9feeb1e65455aff352d5b66a53e4857201239f5d..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[rh-hemartin]

/fs-review

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 7:46 AM UTC · Completed 7:59 AM UTC
Commit: 17eed93 · View workflow run →

[fullsend-ai-review]

Review

Findings

Medium

• [technical documentation accuracy] AGENTS.md:37 — The per-repo chain description claims the call path is "shim template → reusable-dispatch.yml → reusable workflow (.github/workflows/reusable-<agent>.yml)", but reusable-dispatch.yml inlines all stage logic per ADR 62 and does not call reusable-<agent>.yml workflows. Confirmed: the file's own header comments explicitly state stages are inlined to eliminate the second workflow_call hop, and grep for uses:.*reusable- returns zero matches — all six stage jobs (triage, code, review, fix, retro, prioritize) are defined inline. The per-org chain description is correct (scaffold thin callers do call reusable-<agent>.yml via __REUSABLE_WORKFLOW__). This mismatch could lead reviewers to check a non-existent forwarding hop while missing the real concern: that reusable-dispatch.yml's inlined stage jobs must also receive any new secrets/inputs.
  Remediation: Update the per-repo chain bullet to reflect the inlined architecture, e.g.: "Per-repo chain: shim template → reusable-dispatch.yml (which inlines stage logic per ADR 62 rather than calling reusable-<agent>.yml)". Also note that when a secret is added to a reusable-<agent>.yml (used only by per-org callers), the corresponding inlined stage in reusable-dispatch.yml may also need the same secret for per-repo mode.

• [protected-path] AGENTS.md — This PR modifies AGENTS.md, which is a protected path requiring human approval. The change is well-contextualized (linked to issue Broaden AGENTS.md workflow sync guidance to cover reusable workflow secret/input threading #4071 with clear rationale), but human approval is always required for protected-path changes regardless of context.

---

Labels: PR modifies AGENTS.md documentation about workflow contracts and dispatch patterns

[fullsend-ai-review]

See the review comment for full details.

[rh-hemartin]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 7:28 AM UTC · Completed 7:32 AM UTC
Commit: 7ada4e0 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Disagreed with both review findings. The substantive finding (per-repo chain inlining) is factually incorrect: reusable-dispatch.yml currently calls reusable-.yml via uses: references (6 matches), matching what the PR documents. ADR 62 decided to inline stages but this has not been implemented yet. The protected-path finding is procedural and already handled by labels. No code changes needed.

Disagreed (2):

1. per-repo chain description claims reusable-dispatch.yml calls reusable-.yml, but reviewer says stages are inlined per ADR 62: The reviewer's claim is factually incorrect. reusable-dispatch.yml currently DOES call reusable-.yml via uses: references — grep for 'uses:.*reusable-' returns 6 matches (triage, code, review, fix, retro, prioritize). The file's own header comments explicitly state 'Flow: shim (per-repo) → reusable-dispatch.yml → reusable-{stage}.yml' with 3 levels of workflow_call nesting. ADR 62 decided to eventually inline the stages, but this has not yet been implemented. The PR's per-repo chain description accurately reflects the current architecture.
2. AGENTS.md is a protected path requiring human approval: This is a procedural observation, not an actionable code fix. The PR already carries the requires-manual-review label. Human approval is correctly required and will be handled through the normal review process.

Tests: passed

_{Updated by fullsend fix agent}

[waynesun09]

Automated review-squad pass (3 independent reviewer agents + manual verification against the actual workflow YAML, ADRs 0044/0062, and existing test coverage in this repo). All findings below were independently confirmed against real files on this branch before posting; nothing below was hallucinated or based on pre-existing (out-of-diff) issues alone. One MEDIUM finding from a prior review round (the per-repo chain being "already inlined") was re-checked and confirmed still correctly refuted — not re-raised here.

[rh-hemartin]

/fs-fix

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 3:05 PM UTC · Completed 3:13 PM UTC
Commit: 7ada4e0 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 1 (human-triggered)

Addressed 1 of 2 review findings. Updated the per-repo chain bullet in AGENTS.md to reference ADR 62, which will eventually inline stages into reusable-dispatch.yml. The review agent incorrectly claimed stages were already inlined, but the spirit of making the guidance forward-looking is valid. Disagreed with the protected-path finding (procedural, not actionable).

Fixed (1):

1. per-repo chain description does not account for ADR 62 stage inlining (AGENTS.md): Updated the per-repo chain bullet to reference ADR 62 (accepted), which will inline stages into reusable-dispatch.yml and collapse the two-hop forwarding chain to a single hop. The current chain description remains accurate (reusable-dispatch.yml still calls reusable-.yml via uses: references), but the parenthetical now alerts readers that ADR 62 will change this architecture and that new secrets must then be threaded to inlined stage jobs directly.

Disagreed (1):

1. AGENTS.md is a protected path requiring human approval: This is a procedural observation, not an actionable code fix. The PR already carries the requires-manual-review label and modifies only AGENTS.md. Human approval is required by design and is handled through the normal review process.

Tests: passed

Decision points

• Chose to update per-repo chain with ADR 62 reference rather than rewriting the chain to describe an inlined architecture that does not yet exist (alternatives: Rewrite per-repo chain to describe inlined architecture (factually incorrect — ADR 62 not yet implemented), Disagree again as previous iteration did; rationale: The review agent incorrectly believed stages were already inlined, but the underlying concern (guidance should be forward-looking) is valid. Adding the ADR 62 reference keeps the docs accurate about the current state while alerting readers to the planned change.)

_{Updated by fullsend fix agent}

[github-actions]

Site preview

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

Commit: 38d7a5826ff277c58afa1a9718075bdbf8970ad8

[waynesun09]

Recheck pass on the current head (1c0cb7b) against the six findings from the prior review-squad pass (posted against 21052ce).

Status of prior findings:

• 5 of 6 are unchanged in the current head and remain open — not re-posted here to avoid duplicating the existing threads (AGENTS.md:34 "or variables" claim; AGENTS.md:36 per-org chain / ADR 44; AGENTS.md:34 missing env: consumption reminder; AGENTS.md:39 "silent empty string" overgeneralization; AGENTS.md:41 missing anti-over-forwarding/test-coverage reminder).
• The 6th (AGENTS.md:37, per-repo chain / ADR 62) got a real edit, but the edit introduced a new inaccuracy rather than resolving the original one — reopened and detailed in the inline comment below.

One new finding below (HIGH), independently corroborated by 4 reviewer agents (claude-coder, claude-researcher, grok-review-agent, cursor-code-review) against current main, plus a direct branch-divergence check.

[rh-hemartin]

/fs-fix rebase and move the guidance to its appropriate place, also read feedback and apply it.

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 6:31 AM UTC · Completed 6:39 AM UTC
Commit: 1c0cb7b · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Rebased onto main (507 commits behind) and moved workflow contracts guidance to docs/contributing/workflow-contracts.md, matching the restructured AGENTS.md pattern. Addressed all 7 review findings: corrected the vars/secrets claim, updated per-repo chain to reflect ADR 62 inlining, added ADR 44 deprecation to per-org chain, clarified required-flag consistency for silent failures, added env: injection-prevention guidance, warned against secrets: inherit, and referenced existing automated tests.

Fixed (7):

1. branch 507 commits behind main; AGENTS.md restructured: Rebased onto main. Moved workflow contracts guidance from inline AGENTS.md content to docs/contributing/workflow-contracts.md (matching the new contributing-docs structure on main). Added table entry in AGENTS.md and cross-reference in go-code.md.
2. GHA reusable workflows do not inherit secrets or variables — incorrect for variables: Dropped 'or variables' from the claim. Now states secrets only, with a parenthetical noting that repository/organization-level vars are automatically visible and do not need forwarding.
3. per-repo chain describes a two-hop path that no longer exists on main: Rewrote per-repo chain to reflect the already-inlined architecture per ADR 62: shim → reusable-dispatch.yml with inline stage jobs, no separate reusable-.yml hop. Notes standalone reusable-.yml files serve only per-org chain.
4. per-org chain omits dispatch.yml routing hop and ADR 44 deprecation: Added dispatch.yml participation note for routing/event-derived inputs (via gh workflow run -f), and marked the entire per-org chain as deprecated per ADR 44 with a link.
5. silent empty string framing overgeneralizes required-flag behavior: Clarified that omitting a secret required at every hop fails loudly, while a secret with required: false at any upstream hop can arrive empty at a downstream required: true consumer. Added FULLSEND_GCP_WIF_PROVIDER as a concrete example. Emphasized required-flag consistency across the whole chain.
6. no reminder to consume newly-threaded inputs safely (injection risk): Added 'Security — consuming threaded inputs' section: consume user/event-controlled data via env: in run: steps, never interpolate directly. Cross-references the Security note atop reusable-dispatch.yml.
7. review instruction has no anti-over-forwarding caveat and no reference to existing tests: Added warning against secrets: inherit with OTEL_EXPORTER_OTLP_TRACES_HEADERS as a concrete example of scoped forwarding. Referenced workflow_call_alignment_test.go, TestWorkflowCallInputAlignment, and TestOTELHeadersSecretThreading. Recommended extending those tests for new optional secrets.

Tests: passed

Strategy change: Previous iterations disagreed with findings by checking the stale PR branch instead of main. This iteration rebased first, then verified all claims against current main — confirming the reviewers were correct about the inlined architecture.

Decision points

• Chose to create a new docs/contributing/workflow-contracts.md file rather than expanding the existing go-code.md section (alternatives: Expand the Dispatch workflows section inline in go-code.md, Add guidance directly to AGENTS.md; rationale: AGENTS.md was restructured on main to use a table pointing to docs/contributing/ files. Workflow contracts guidance applies beyond Go code changes (any reusable workflow modification), so a dedicated file matches the contributing-docs pattern better than go-code.md.)
• Moved the full dispatch sync paragraph (including GitLab scaffold mention) to workflow-contracts.md rather than keeping it in go-code.md (alternatives: Keep dispatch sync in go-code.md and only add threading guidance to new file, Duplicate the paragraph in both files; rationale: The dispatch sync concern is about workflow files, not Go code per se. A single authoritative location avoids content drift. go-code.md retains a cross-reference.)

_{Updated by fullsend fix agent}

[rh-hemartin]

/fs-fix rebase and resolve conflicts

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 12:58 PM UTC · Completed 1:03 PM UTC
Commit: ed1ad64 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Rebased onto latest main and resolved AGENTS.md merge conflict. The conflict was between new table rows added on main ([Behaviour Testing], [CI Workflows]) and this branch's [Workflow Contracts] row. All rows are preserved in the resolved file. Markdown link linter passes. Branch needs force-push.

Fixed (1):

1. rebase and resolve conflicts: Rebased branch onto origin/main and resolved merge conflict in AGENTS.md. The conflict occurred because main added [Behaviour Testing] and [CI Workflows] rows to the topic-specific guidance table, while this branch added a [Workflow Contracts] row in the same area. Resolved by keeping all three new rows in correct order: [Behaviour Testing], [Workflow Contracts], then [CI Workflows]. The intro text update from main (adding docs/guides/ reference) was also preserved.

Tests: passed

_{Updated by fullsend fix agent}

[rh-hemartin]

/fs-fix rebase

[fullsend-ai-coder]

🤖 Finished Fix · ✅ Success · Started 9:45 AM UTC · Completed 9:53 AM UTC
Commit: 116be14 · View workflow run →

[fullsend-ai-coder]

🔧 Fix agent — iteration 2 (human-triggered)

Rebased PR branch onto latest origin/main as requested. No conflicts. The commit was cleanly replayed. All 3 changed files (AGENTS.md, docs/contributing/go-code.md, docs/contributing/workflow-contracts.md) are intact. Go tests pass (failures in internal/binary, internal/cli, internal/fetch are sandbox network restrictions, not related to this PR).

Fixed (1):

1. rebase PR branch onto latest main: Rebased branch agent/4071-broaden-workflow-sync-guidance onto origin/main (tip: 5e2b160). The single PR commit (116be14) was cleanly replayed as 38d7a58 with no conflicts. The branch now sits directly on top of the latest main, incorporating 5 merge commits that had landed since the branch diverged.

Tests: passed

_{Updated by fullsend fix agent}

[rh-hemartin]

@waynesun09 anything else here?

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:09 AM UTC · Completed 8:25 AM UTC
Commit: 38d7a58 · View workflow run →

[fullsend-ai-retro]

Retro: PR #4075 — broaden workflow sync guidance

Timeline: Issue #4071 was filed by the retro agent on Jul 10 based on a retro of PR #3903. The code agent created PR #4075 the same day (3 files, 16 additions). The PR sat 11 days without review until a human triggered /fs-review on Jul 21. The review agent found 2 medium findings. The fix agent then ran 5 times across 8 days (2 substantive fixes, 3 rebases) before the PR was approved and merged on Jul 30 — 20 days total.

Key finding — fix agent stale-branch verification: The fix agent's first run (Jul 22, run 29900226359) incorrectly disagreed with the review agent's finding that reusable-dispatch.yml had already inlined stages per ADR 62. The fix agent checked the PR branch's copy of the file (507 commits behind main) and concluded the reviewer was wrong. A human reviewer (waynesun09) later confirmed the review agent was directionally correct by checking main. This wasted 2 fix iterations and required detailed human intervention. The fix agent itself acknowledged the error in its third run: "Previous iterations disagreed with findings by checking the stale PR branch instead of main."

Review quality gap: The review agent found 2 of 8 real issues. The human reviewer, using a 3-agent review squad with manual verification, found 6 additional HIGH/MEDIUM findings (incorrect vars claim, missing injection-prevention guidance, per-org chain omitting dispatch.yml hop and ADR 44 deprecation, silent-failure overgeneralization, missing anti-over-forwarding caveat, missing test-coverage reference) plus caught a new inaccuracy the fix agent introduced.

Review dispatch gap: The ready-for-review label was applied by the coder bot on Jul 10 at 19:05 UTC, but the review agent did not run until Jul 21 when a human manually triggered /fs-review. This 11-day gap is evidence for issues #3998 and #4858.

Evidence for existing issues:

• #4953: Additional evidence — fix agent DID read the file but from the stale PR branch, leading to an incorrect disagreement. This case shows that Fix agent must verify source files before using 'Disagreed' to dismiss review findings #4953's proposed fix (require reading the file) may be insufficient — the agent also needs to read from the correct branch.
• #2199, #5297, #1480: Review agent found 2 of 8 issues on a documentation PR about GHA workflow architecture. Human review squad found 6 additional findings by cross-referencing actual workflow files, ADRs, and test code.
• #1275: The review agent correctly flagged the per-repo chain description as inaccurate but didn't trace the full workflow_call chain to provide authoritative evidence, making it easier for the fix agent to dismiss.

Proposals filed

• Fix agent should verify codebase-state claims against the base branch before disagreeing (in fullsend-ai/fullsend)