refactor(workflows): replace fullsend_ai_ref by job.workflow_sha

[rh-hemartin]

Resolves #2683

Summary

• Stage workflows use job.workflow_repository/job.workflow_sha to checkout upstream defaults instead of caller-provided fullsend_ai_ref
• No caller passes fullsend_ai_ref anymore (shim-per-repo, dispatch, per-org thin callers)
• Input kept (deprecated) in stage workflows and dispatch so existing deployed shims don't break when v0 moves
• ADR 35 annotated with supersession note
• actionlint ignore added for job.workflow_sha (not in actionlint's type defs yet)

Context

GitHub Actions job.workflow_* context lets a reusable workflow identify its own source repo and SHA — guaranteed consistent with the uses: line. Eliminates drift between fullsend_ai_ref and the @ref.

Test plan

• go test ./internal/scaffold/... passes
• All pre-commit hooks pass
• Trigger per-repo run to verify upstream defaults checkout resolves correctly
• Verify per-org run still works (deployed thin callers may still pass fullsend_ai_ref — accepted and ignored)

🤖 Generated with Claude Code

[qodo-code-review]

PR Summary by Qodo

refactor(workflows): use job.workflow_sha for upstream defaults checkout
⚙️ Configuration changes 📝 Documentation 🧪 Tests 🕐 40+ Minutes

Description

• Stage workflows self-checkout upstream defaults via job.workflow_repository/job.workflow_sha.
• Deprecate fullsend_ai_ref input while keeping it for backward compatibility.
• Update scaffolding/templates/tests and actionlint config to reflect the new contract.

Diagram

graph TD
  A["Caller workflow (shim/thin)"] --> B["reusable-dispatch.yml"] --> C["Stage reusable workflows"] --> D["job.workflow_* context"] --> E["Checkout upstream defaults"] --> F["fullsend-ai/fullsend repo"]
  A -.-> G["fullsend_ai_ref (deprecated)"] -.-> C

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep fullsend_ai_ref as the source of truth

• ➕ Works on older GitHub Actions runners/context implementations
• ➕ Explicit input makes behavior obvious to callers
• ➖ Allows drift between the reusable workflow ref (uses:@ref) and the checkout ref
• ➖ Requires all callers to be updated/pinned correctly

2. Hardcode upstream defaults checkout to @v0

• ➕ Simplest mental model; no context dependencies
• ➕ Avoids passing inputs and avoids actionlint context gaps
• ➖ Cannot test or roll out default changes safely per-caller
• ➖ Decouples defaults from the actual workflow version being executed

3. Validate fullsend_ai_ref matches the uses: ref and fail on mismatch

• ➕ Detects drift explicitly and prevents silent mismatches
• ➕ Preserves the existing input contract
• ➖ More plumbing and failure modes in dispatch/stage workflows
• ➖ Still relies on callers to provide a ref

Recommendation: Proceed with the current approach: using job.workflow_repository/job.workflow_sha makes the checkout ref inherently consistent with the reusable workflow version selected by the caller’s uses: line, eliminating a common drift class. Keeping the deprecated input avoids breaking deployed shims while allowing gradual migration.

Files changed (17) +28 / -37

Tests (1) +3 / -3

render_test.goUpdate scaffold rendering tests to assert fullsend_ai_ref absence +3/-3

Update scaffold rendering tests to assert fullsend_ai_ref absence

• Adjusts tests to assert that rendered thin callers and shims no longer include the fullsend_ai_ref input, including the default-ref fallback case.

internal/scaffold/render_test.go

Documentation (1) +3 / -1

0035-layered-content-resolution.mdAnnotate ADR 35 with job.workflow_sha supersession note +3/-1

Annotate ADR 35 with job.workflow_sha supersession note

• Updates the ADR narrative to note that caller-controlled fullsend_ai_ref has been superseded by job.workflow_sha, which removes the need to pass a ref.

docs/ADRs/0035-layered-content-resolution.md

Other (15) +22 / -33

reusable-code.ymlSelf-checkout defaults via job.workflow_repository/job.workflow_sha +3/-3

Self-checkout defaults via job.workflow_repository/job.workflow_sha

• Deprecates the fullsend_ai_ref input description and switches the upstream defaults checkout to use job.workflow_repository and job.workflow_sha instead of the caller-provided ref.

.github/workflows/reusable-code.yml

reusable-dispatch.ymlStop forwarding fullsend_ai_ref to stage workflows; document new behavior +2/-8

Stop forwarding fullsend_ai_ref to stage workflows; document new behavior

• Keeps fullsend_ai_ref as a deprecated input for compatibility but removes passing it into downstream stage reusable workflows. Updates commentary to reflect that stage workflows self-checkout defaults via job.workflow_sha.

.github/workflows/reusable-dispatch.yml

reusable-fix.ymlUse job.workflow_sha for upstream defaults checkout +3/-3

Use job.workflow_sha for upstream defaults checkout

• Marks fullsend_ai_ref deprecated and updates the defaults checkout step to use job.workflow_repository/job.workflow_sha.

.github/workflows/reusable-fix.yml

reusable-prioritize.ymlUse job.workflow_sha for upstream defaults checkout +3/-3

Use job.workflow_sha for upstream defaults checkout

• Marks fullsend_ai_ref deprecated and updates the defaults checkout step to use job.workflow_repository/job.workflow_sha.

.github/workflows/reusable-prioritize.yml

reusable-retro.ymlUse job.workflow_sha for upstream defaults checkout +3/-3

Use job.workflow_sha for upstream defaults checkout

• Marks fullsend_ai_ref deprecated and updates the defaults checkout step to use job.workflow_repository/job.workflow_sha.

.github/workflows/reusable-retro.yml

reusable-review.ymlUse job.workflow_sha for upstream defaults checkout +3/-3

Use job.workflow_sha for upstream defaults checkout

• Marks fullsend_ai_ref deprecated and updates the defaults checkout step to use job.workflow_repository/job.workflow_sha.

.github/workflows/reusable-review.yml

reusable-triage.ymlUse job.workflow_sha for upstream defaults checkout +3/-3

Use job.workflow_sha for upstream defaults checkout

• Marks fullsend_ai_ref deprecated and updates the defaults checkout step to use job.workflow_repository/job.workflow_sha.

.github/workflows/reusable-triage.yml

.pre-commit-config.yamlAllow actionlint to ignore missing workflow_sha typing +2/-0

Allow actionlint to ignore missing workflow_sha typing

• Adds an actionlint ignore for 'property "workflow_sha" is not defined', matching the existing ignore for workflow_repository until actionlint type definitions catch up.

.pre-commit-config.yaml

code.ymlStop templating fullsend_ai_ref into scaffolded code workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded code workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation so generated repos no longer pass a ref shim.

internal/scaffold/fullsend-repo/.github/workflows/code.yml

fix.ymlStop templating fullsend_ai_ref into scaffolded fix workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded fix workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation.

internal/scaffold/fullsend-repo/.github/workflows/fix.yml

prioritize.ymlStop templating fullsend_ai_ref into scaffolded prioritize workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded prioritize workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation.

internal/scaffold/fullsend-repo/.github/workflows/prioritize.yml

retro.ymlStop templating fullsend_ai_ref into scaffolded retro workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded retro workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation.

internal/scaffold/fullsend-repo/.github/workflows/retro.yml

review.ymlStop templating fullsend_ai_ref into scaffolded review workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded review workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation.

internal/scaffold/fullsend-repo/.github/workflows/review.yml

triage.ymlStop templating fullsend_ai_ref into scaffolded triage workflow +0/-1

Stop templating fullsend_ai_ref into scaffolded triage workflow

• Removes the fullsend_ai_ref input from the scaffolded per-org workflow invocation.

internal/scaffold/fullsend-repo/.github/workflows/triage.yml

shim-per-repo.yamlStop templating fullsend_ai_ref into per-repo shim +0/-1

Stop templating fullsend_ai_ref into per-repo shim

• Removes fullsend_ai_ref from the generated shim-per-repo dispatch workflow inputs so pinned-SHA shims don’t pass an unnecessary ref.

internal/scaffold/fullsend-repo/templates/shim-per-repo.yaml

[github-actions]

Site preview

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

Commit: 3166d95205d2b211c514484b0de72eceb8fb4373

[fullsend-ai-review]

🤖 Review · ⚠️ Cancelled · Started 12:17 PM UTC · Ended 12:22 PM UTC
Commit: 2d8adb7 · View workflow run →

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (3) 📘 Rule violations (2) 📎 Requirement gaps (0) 📜 Skill insights (0)

Context used

✅ Tickets: 🎫 reusable-workflow and dependabot update

✅ Compliance rules (platform): 58 rules

✅ Skills: writing-user-docs, writing-adrs

1. Stale workflows layer assertion 🐞 Bug ≡ Correctness

Description

CI runs go test ./..., but internal/layers/TestWorkflowsLayer_Install_PinnedSHA still asserts
that scaffolded triage.yml contains a fullsend_ai_ref: line even though the triage workflow
template no longer renders it, causing a test failure.

Code

internal/scaffold/fullsend-repo/.github/workflows/triage.yml[R35-38]

      mint_url: ${{ vars.FULLSEND_MINT_URL }}
      gcp_region: ${{ vars.FULLSEND_GCP_REGION }}
      install_mode: per-org
-      fullsend_ai_ref: __FULLSEND_AI_REF__
      runner_image: __GH_RUNNER__

Relevance

⭐⭐⭐ High

Stale scaffold/test expectations are commonly updated when templates change (accepted test assertion
updates in PR #1039).

PR-#1039

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The scaffolded triage thin-caller template no longer includes fullsend_ai_ref in its with:
block, but internal/layers still asserts it must be present. Since CI executes `go test -race ...
./...`, that stale assertion will be exercised and fail.

internal/scaffold/fullsend-repo/.github/workflows/triage.yml[28-41]
internal/layers/workflows_test.go[244-264]
.github/workflows/lint.yml[45-52]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`internal/layers/workflows_test.go` expects scaffolded `triage.yml` to include `fullsend_ai_ref`, but the scaffold template was changed to omit it. CI runs `go test ./...`, so this mismatch will likely fail tests.

### Issue Context
The thin caller templates under `internal/scaffold/fullsend-repo/.github/workflows/` removed `fullsend_ai_ref` from the `with:` block; the corresponding layer test was not updated.

### Fix Focus Areas
- internal/layers/workflows_test.go[244-264]
- internal/scaffold/fullsend-repo/.github/workflows/triage.yml[28-41]
- .github/workflows/lint.yml[45-52]

### Suggested change
Adjust `TestWorkflowsLayer_Install_PinnedSHA` to stop asserting `fullsend_ai_ref:` is present (optionally assert it is absent), while keeping/adding assertions that the `uses:` line is pinned to the upstream SHA and carries the tag comment.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. actionlint ignore added 📘 Rule violation ▣ Testability

Description

The PR weakens linting by adding a new actionlint ignore for workflow_sha without an inline,
time-bounded suppression rationale. This can allow real workflow schema issues to slip through
unnoticed over time.

Code

.pre-commit-config.yaml[R91-92]

+          - property "workflow_sha" is not defined
+          - -ignore

Relevance

⭐⭐⭐ High

Repo already accepts adding actionlint ignores in pre-commit for unsupported schema keys (PR #1030).

PR-#1030

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062076 disallows weakening linters to make checks pass unless narrowly justified
and managed. The PR adds an actionlint ignore for workflow_sha, expanding the set of ignored
findings.

Rule 1062076: Do not weaken tests or linters to make failures pass
.pre-commit-config.yaml[85-95]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A new `actionlint` ignore was added for `property "workflow_sha" is not defined`, which weakens linting without an inline, time-bounded rationale.

## Issue Context
Exceptions to weakening linters should include clear justification and a plan to remove the suppression (e.g., link to an upstream issue/PR and a TODO/owner/date).

## Fix Focus Areas
- .pre-commit-config.yaml[85-95]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. ADR PR placeholder left 🐞 Bug ⚙ Maintainability

Description

ADR 0035 now contains the placeholder text PR #XXXX, leaving an inaccurate supersession reference
in committed documentation.

Code

docs/ADRs/0035-layered-content-resolution.md[R64-66]

+caller-controlled ref; since superseded by `job.workflow_sha` which
+eliminates the need for the caller to pass a ref — see PR #XXXX),
+copies them into the main dirs (`agents/`, `skills/`,

Relevance

⭐⭐⭐ High

ADR/doc placeholder and wrong reference fixes are typically accepted (e.g., ADR cross-ref
corrections in PR #1549).

PR-#1549

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The ADR text explicitly includes a PR #XXXX placeholder in the newly added supersession note.

docs/ADRs/0035-layered-content-resolution.md[60-66]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The ADR references a placeholder `PR #XXXX`, which is incorrect once merged and reduces traceability.

### Issue Context
This was introduced as part of documenting the supersession of the caller-controlled ref approach.

### Fix Focus Areas
- docs/ADRs/0035-layered-content-resolution.md[60-66]

### Suggested change
Replace `PR #XXXX` with the actual PR number for this change, or rephrase to avoid hardcoding a PR number (e.g., "see the refactor that switched to job.workflow_sha").

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Testing guide now misleading 🐞 Bug ⚙ Maintainability

Description

docs/guides/dev/testing-workflows.md still instructs developers to set fullsend_ai_ref to
control runtime defaults/actions, but stage workflows now checkout defaults using job.workflow_sha
and dispatch no longer threads fullsend_ai_ref, so following the guide will not affect the
defaults checkout path.

Code

.github/workflows/reusable-triage.yml[R75-76]

          path: .defaults
          fetch-depth: 1

Relevance

⭐⭐⭐ High

Team often accepts “docs out of sync with behavior” fixes, incl testing-workflows guide updates (PR
#1954).

PR-#1954

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The guide states fullsend_ai_ref controls runtime defaults/actions and shows setting it, but the
updated reusable workflows checkout defaults at job.workflow_sha and the dispatch workflow no
longer passes fullsend_ai_ref to stage workflows, so that input no longer governs the defaults
checkout behavior described by the guide.

docs/guides/dev/testing-workflows.md[7-20]
docs/guides/dev/testing-workflows.md[48-92]
.github/workflows/reusable-triage.yml[69-76]
.github/workflows/reusable-dispatch.yml[422-444]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
The workflow testing guide claims `fullsend_ai_ref` controls which defaults/actions are loaded at runtime and provides examples setting it. After this PR, stage workflows self-checkout via `job.workflow_sha` (derived from the `uses:` ref), and dispatch no longer passes `fullsend_ai_ref` into stage workflows, so those guide steps won't do what they say.

### Issue Context
The repo intentionally keeps `fullsend_ai_ref` as a deprecated input for compatibility, but it is no longer the mechanism for selecting the upstream defaults checkout.

### Fix Focus Areas
- docs/guides/dev/testing-workflows.md[7-13]
- docs/guides/dev/testing-workflows.md[48-92]
- .github/workflows/reusable-triage.yml[69-76]
- .github/workflows/reusable-dispatch.yml[422-444]

### Suggested change
Update the guide to explain that the `uses: ...@<ref>` controls the workflow identity and therefore the defaults checkout via `job.workflow_sha`; remove or clearly mark `fullsend_ai_ref` examples as deprecated/ineffective for defaults checkout, and provide updated testing steps (change only the `uses:` ref, plus `fullsend_version` if needed).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

View more (1)

5. Comment-only hunk in reusable-dispatch.yml 📘 Rule violation ⚙ Maintainability

Description

A standalone comment change was made without any adjacent functional/code change in the same diff
hunk. This violates the rule against comment-only diffs outside the issue’s code changes and makes
audit/review harder.

Code

.github/workflows/reusable-dispatch.yml[430]

+    # Stage workflows use job.workflow_sha to self-checkout upstream defaults.

Relevance

⭐⭐ Medium

No prior accepted/rejected reviews found enforcing “no comment-only hunks” in workflow YAML; unclear
team practice.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062072 flags hunks where only comments change. The diff shows only the comment
line being modified near the triage job, with uses: unchanged in that hunk.

Rule 1062072: Do not add or modify comments outside code lines changed for the issue
.github/workflows/reusable-dispatch.yml[429-431]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A comment was modified in a diff hunk that contains no functional/code changes, which violates the comment-only change restriction.

## Issue Context
In `.github/workflows/reusable-dispatch.yml`, the hunk at the triage job only changes a comment line.

## Fix Focus Areas
- .github/workflows/reusable-dispatch.yml[429-431]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 12:25 PM UTC · Completed 12:38 PM UTC
Commit: 11ee242 · View workflow run →

[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

• [stale-reference] docs/plans/automatic-updates.md:18 — Plan document describes fullsend_ai_ref as the active mechanism for controlling action checkout refs (lines 18, 31, 40, 64) and proposes renaming it to fullsend_actions_ref. After this PR, fullsend_ai_ref is deprecated and job.workflow_sha is the operative mechanism. The plan document now describes a superseded approach.
  Remediation: Update docs/plans/automatic-updates.md to reflect that fullsend_ai_ref has been deprecated in favor of job.workflow_sha, and that the proposed rename to fullsend_actions_ref is no longer the planned trajectory.

• [protected-path] .github/workflows/, .pre-commit-config.yaml — This PR modifies 7 files under .github/workflows/ and .pre-commit-config.yaml, which are protected paths requiring human approval. The PR links to issue reusable-workflow and dependabot update #2683 and provides clear rationale for the changes. Protected files modified: .github/workflows/reusable-code.yml, .github/workflows/reusable-dispatch.yml, .github/workflows/reusable-fix.yml, .github/workflows/reusable-prioritize.yml, .github/workflows/reusable-retro.yml, .github/workflows/reusable-review.yml, .github/workflows/reusable-triage.yml, .pre-commit-config.yaml.

Previous run

Review

Findings

Medium

• [stale reference] docs/guides/dev/testing-workflows.md:12 — Developer guide instructs contributors to set fullsend_ai_ref when testing workflow changes (lines 12, 18, 68, 89). After this PR, stage workflows ignore fullsend_ai_ref and use job.workflow_sha instead. Following these instructions will have no effect on the checkout ref used by stage workflows.
  Remediation: Update the documentation to note that fullsend_ai_ref is deprecated and no longer controls the checkout ref in stage workflows. Explain that the checkout ref is now derived automatically from job.workflow_sha.

• [protected-path] .github/workflows/, .pre-commit-config.yaml — This PR modifies 7 files under .github/workflows/ and .pre-commit-config.yaml, which are protected paths requiring human approval. The PR links to issue reusable-workflow and dependabot update #2683 and provides clear rationale for the changes. Protected files modified: .github/workflows/reusable-code.yml, .github/workflows/reusable-dispatch.yml, .github/workflows/reusable-fix.yml, .github/workflows/reusable-prioritize.yml, .github/workflows/reusable-retro.yml, .github/workflows/reusable-review.yml, .github/workflows/reusable-triage.yml, .pre-commit-config.yaml.

---

Labels: PR modifies reusable workflow dispatch files and CI pipeline configuration to replace fullsend_ai_ref with job.workflow_sha.

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 1:04 PM UTC · Completed 1:17 PM UTC
Commit: 3166d95 · View workflow run →

[ifireball]

LGTM, one small cleanup nit.

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 6:32 AM UTC · Completed 6:40 AM UTC
Commit: 3166d95 · View workflow run →

[fullsend-ai-retro]

Retro: PR #2689 — refactor(workflows): replace fullsend_ai_ref by job.workflow_sha

Human-authored PR by rh-hemartin, merged after ~3 days. Review agent ran 3 times (1 cancelled by force-push, 2 successful with identical findings). Qodo also reviewed. One human reviewer (ifireball) approved with a nit.

What went well

• Concurrency cancellation worked correctly. The first review agent run was cancelled when a force-push landed mid-review — no stale findings were posted.
• Review agent correctly identified stale documentation references in docs/plans/automatic-updates.md and flagged protected-path changes requiring human approval.
• Human reviewer's domain knowledge added value, though the specific dead-code finding about render.go was actually incorrect (__FULLSEND_AI_REF__ template placeholder ≠ fullsend_ai_ref workflow input — the former is still actively used).

What could go better

• Redundant 3rd review run: The third force-push (13:01 UTC) triggered another full review that produced identical findings to the 2nd run. Already tracked by Debounce review dispatch on rapid synchronize events #1014 (debounce review dispatch on rapid synchronize events).
• Placeholder marker detection: Qodo caught PR #XXXX in ADR 0035 that the review agent missed. One proposal filed below.
• Stale reference cross-checking: The review agent flagged stale docs but this capability is already being tracked by Review agent: cross-reference external identifiers in docs against codebase #2172.

Proposals

1 new proposal filed. 3 candidate proposals skipped as duplicates of existing issues (#1014, #2172, #2329).

Proposals filed

• Review agent should detect placeholder/stub markers in committed content (in fullsend-ai/fullsend)