✨🧑‍💻 - Generate verification setup starter preserve consumer actions and expose wizard activation #656

Is there an existing issue or feature request for this?

• I have searched the existing issues and feature requests.

What area does this improvement affect?

New Feature

What actions does this improvement affect?

Issue, Pull Request, Commit

Description of the idea or improvement

Complete onboarding for the native repository-owned verification setup introduced by #647 and merged in #652.

The maintainer explicitly requests that copilot setup create .github/actions/copilot-verification-setup/action.yml when missing, preserve an existing consumer action, expose VERIFICATION_SETUP activation in the shared terminal/web wizard, document upgrades, and deliver a PR merged into develop only after all applicable final-head checks pass and no findings remain unresolved.

Accepted product contract for this follow-up:

• Initial setup and workflow upgrades offer a visible create/preserve result for the fixed consumer action path. Create only if absent; preserve existing regular-file bytes and auxiliary files on repeated setup, workflow updates, deselection and batch maintenance. Consumer assets stay outside generator overwrite/retirement ownership.
• Ship a minimal native composite starter. Do not infer languages, dependencies or commands, or execute installation during setup. The starter explicitly fails with a customization instruction until the owner replaces its placeholder step, preventing an empty template from claiming readiness.
• Keep the existing repository.verificationSetup boolean and VERIFICATION_SETUP binding, disabled by default. Add an explicit boolean question to the shared repository questionnaire, with help and plan/result guidance for both terminal and web entrypoints. Respect preselected/configured values and organization reuse. Enabling the flag does not mean the dependency template is configured or reviewed on MAIN_BRANCH.
• The review must explain: create versus preserve, flag enabled/disabled, customize/review/merge on the configured trusted main branch, and run a real verification afterward. Creating an installer PR is not proof of runtime readiness.
• Dry-run, canceled setup and declined approval write nothing. Missing-only creation must not follow unsafe parent links, overwrite collisions or truncate a file created between preview and Apply. Unsafe paths and invalid file kinds produce actionable blockers while preserving existing contents.
• Include the starter in the published npm package and in local and batch setup; keep existing manifest receipts, permission checks, review gates, runner selections and credential handling intact.
• Document the three separate upgrade layers: installed CLI, remote Action ref (@v3 versus exact version/SHA), and committed generated workflows. Give an ordered migration and rollback procedure and explain that a merge into develop is not a published release.

Current limitations or challenges

The current installer generates event workflows but no consumer setup action. verificationSetup can be provided in config and becomes a Variable, but there is no dedicated wizard question. Users must discover and create the file themselves, then assemble an upgrade process from separate documents. The existing action is intentionally consumer-owned and must remain protected from later generator updates.

Evidence: src/utils/setup_files.ts, src/application/policies/setup_questionnaire_policy.ts, src/application/policies/setup_configuration_plan.ts, src/infrastructure/__tests__/verification_setup_configuration.test.ts, and docs/security-operations/operations/verification.mdx on develop. Last published release remains 3.9.3; native setup support is merged but not released.

Expected impact

A new or existing project gets one discoverable starter file, an explicit activation decision, and a reviewable upgrade plan without patching generated Copilot workflows. Existing project-specific actions remain byte-for-byte intact.

Acceptance includes absent/existing files; repeated upgrades; disabled and enabled flags; config and wizard parity; preview, cancel and decline; collision and symlink safety; local and batch installation; npm package assets; clear template customization diagnostics; migration and rollback docs; specifications/catalog and generated artifacts. Minimum 48 distinct focused cases across file ownership/races, questionnaire/config, plan/dry-run/batch, UX/docs and packaging/integration/security; new pure policy branches 100%, new adapters 95% lines/statements and 90% branches/functions, preserving repository-wide budgets.

Alternatives considered

Requiring every user to create the file and Variable manually leaves onboarding incomplete. Overwriting an existing action destroys project configuration. Inferring dependency installs or shipping a successful no-op would claim preparation without a project-owned definition. Automatic activation remains excluded; the existing explicit opt-in is retained.

Version of copilot

3.9.3 published; follow-up to native composite implementation merged into develop by #652.

Additional context or comments

User authorization covers issue admission, implementation, specifications, tests, documentation, PR and merge into develop after successful checks and resolved findings. It does not request a release or installing changes into other repositories. Preserve unrelated in-flight work on #653 by using an isolated checkout of the exact Action-managed branch.

SDD ownership and proportional recovery

The first admission run (39644820659) stopped without publishing a draft because its SDD update exceeded the bounded size after repair. Resolve this by selecting action: companion, existing capability local-web-setup-assistant, and new companion path specs/verification-setup-onboarding.md. This is an onboarding extension of that existing capability; do not create a new catalog capability or rewrite the large existing assistant SDD. Reference specs/repository-verification-setup-hooks.md for the unchanged native execution contract.

Keep the companion proportional (target 12–18 KiB), with a small flow diagram, the exact create/preserve/activate/upgrade contract above, numeric 48-case risk allocation, unique namespaced scenario IDs and a consistent acceptance trace. All material product choices are already resolved above; the installer remains explicit and the generated starter remains fail-closed until customized. The maintainer authorizes this companion ownership and a retry of the same admitted issue workflow.