🔧🧑‍💻 - refactor centralize native comment verification in a reusable workflow #662

Is there an existing issue for this?

• I have searched the existing issues.

What area does this task affect?

CI/CD

Task description

Encapsulate the complete native verification coordination used by issue-comment and pull-request-review-comment callbacks in one Copilot-owned reusable workflow. Keep the repository callbacks and setup templates compact, with one versioned call instead of copying the setup/continuation sequence into every repository.

The maintainer explicitly requested a separate issue and its own Action-managed branch for this work, then a reviewed PR with all checks passing and no unresolved findings before merging into develop. Complete this dependency before publishing minor release #661 (3.10.0). The release has no deploy label and remains unpublished.

Current issues or inefficiencies

The native composite dependency setup introduced twenty statically declared setup/continue pairs plus final cleanup: 579 added lines in each distributed comment callback, duplicated in the source workflows. The generator keeps them synchronized but exposes internal coordination to every consumer and makes upgrades difficult to review.

A composite coordinator cannot preserve the existing native per-step timeout because GitHub's composite action schema rejects internal timeout-minutes. The maintainer has now selected a reusable workflow owning the complete job. The repository-owned dependency action remains composite; no candidate or worker crosses job boundaries.

Expected impact

Small repository issue/review-comment workflow
 -> versioned Copilot reusable workflow, one job
    -> same-commit Copilot Action
    -> trusted project composite dependency setup
    -> continuation, verifier/publication guards, native post cleanup

Source callbacks use the exact same-commit self-repository workflow reference. Installed callbacks use vypdev/copilot/.github/workflows/copilot_comment_runtime.yml@v3. The coordinator uses GitHub's self-repository Action reference so an exact caller SHA cannot drift to a different Action version. This requires GitHub.com support and runner 2.336.0+; the inspected source runner is 2.337.0. Document platform/runner/Actions-policy prerequisites and pinned-ref upgrades.

Preserve existing admission, bot/fork gates, Variable and Secret semantics, 20 setup boundaries, five-minute native setup cancellation, 300-second worker readiness, 120-minute job budget, candidate identity, trusted-main action pinning, credential-free verifier profiles, one-use continuations, and reverse native post cleanup. The agent or business operation must not be rerun to continue verification. Keep named Secrets explicit and provider credentials scoped to the initial Copilot step; no unrestricted secrets inheritance or provider/PAT inputs to project setup.

Setup must retain or explicitly replace existing scalar/label/group runner routes when migrating native jobs to reusable calls, expose the same route in preview and Apply, and recognize known reusable callers during configuration maintenance. Preserve source-only jobs, consumer action bytes and auxiliary assets. Do not silently drop custom bootstrap steps; require reviewed migration with actionable recovery. Unknown inputs, unsupported source identity, malformed runner JSON and dependent expressions fail closed rather than infer configuration or runner access.

Acceptance: each source/setup comment callback is at most 35 lines; one central workflow owns all native phases. Existing verification and publication behavior, disabled/read-only/dry-run/no-op semantics and current user-facing result cards remain. Update the existing native verification and setup runner SDDs, catalog evidence, user/operator/upgrade docs, tests and generated bundles together. The additional risk-derived floor is 40 distinct cases (16 workflow/security mutations, 12 routing/migration/idempotency, 12 configuration inspection/identity/credential-scope), shared once across the two capabilities. Preserve existing coverage gates; the new pure known-workflow contract targets full branch coverage. Run all repository validators, full coverage, package/build smoke and real native acceptance on Linux, Windows and macOS.

Alternatives considered

Keep generated orchestration in every consumer: rejected because of duplication and review cost. Composite coordinator: rejected because it cannot retain native per-step cancellation. Dispatching another job for candidate setup: rejected because it would break the admitted same-job worker and candidate environment. Removing time limits is not required for encapsulation and is outside this refactor.

Additional context or comments

The architecture choice and current limits have already been resolved with the maintainer in this chat; no material product decision remains open. Use the existing specification ownership: specs/repository-verification-setup-hooks.md under branch-synchronization and specs/setup-runner-profiles-and-installation-parity.md under setup-and-doctor. Related delivered work: #647/#652 and #656/#657. Release #661 is a dependent operation, not the implementation issue for this refactor.

Local implementation drafts are being moved from the isolated release worktree onto the exact new managed branch only after the Action admits the issue and publishes branch readiness. Do not manually create, rename or force-push a managed remote branch. Keep the two unrelated release-review corrections already committed on release/3.10.0 out of this refactor unless a concrete dependency requires them. Do not publish the minor until this issue's implementation and final-head checks/review are complete.

Primary provider contracts: https://github.com/actions/runner/blob/main/src/Runner.Worker/action_yaml.json and https://github.blog/changelog/2026-07-30-reference-same-repository-actions-with-self-repository-syntax/.