[efraespada]

A promotion-only CI failure can require a legitimate source fix after a release/hotfix candidate has already frozen its SHA. Ordinary prepare then rejects the changed source, and publication/reconciliation recovery cannot safely replace that unpublished candidate.

Adds an explicit replace workflow mode: native read-only preflight → complete fresh project preparation and validation → exact candidate/production-base/run/attempt/revision checks → a new durable operation and ordinary protected promotion PR. The old PR must be closed unmerged, and its identity and evidence remain in a bounded audit history. Version, managed branch, origin, title/changelog, locale and policy are preserved. Old callbacks cannot advance the successor; exact replay recovers only the recorded candidate, with no repeated preparation or publication.

Replacement blocks on acceptance/publication effects, any matching native tag or Release (including drafts with proven visibility), foreign/open/queued promotions, stale heads/base/revisions and unavailable authority. The maintainer must independently inspect every project registry and explicitly confirm vacancy. Preflight runtime code is selected by the trusted workflow commit (github.workflow_sha in this repository) or the released standalone subaction in consumers; the supplied source SHA is data. The final native adapter requires successful prerequisite jobs and named verification/identity steps from this exact workflow attempt; generic JSON input overlays cannot synthesize or overwrite replacement proofs. Each path performs one complete native inspection, followed by cheap final source/base ref reads that reject movement during inventory work. Preflight summaries call the unprepared input “Reviewed source” and reserve “Prepared source” for the recorded final candidate, consistently in EN/ES/static fallback. Consumer templates keep replacement disabled in both mode choices and the permissionless validator. Maintainers configure all project validators, enable the workflow-owned literal and then add the replace choice; the failing verifier cannot be skipped. Existing prepare/publish/resume paths and merge protections remain in force; local deployment is rejected.

Validation: complete final coverage passed 772 root Jest suites / 14,091 tests, with 35 existing skips; all global/module budgets and setup acceptance passed. All nine new modules have 100% in four metrics. The final patch audit has 433 executable modified lines covered, zero misses and zero uncovered changed branches. All 267 extension tests pass with 100% in four metrics. Types, lint, architecture, specifications/catalog/ledger, docs/agent docs, workflow contracts and Graphify pass. The real npm package contains 87 files and passes CLI, typed API and isolated local web smoke. Three real standalone-bundle HTTP fixture scenarios verify read-only execution, no profile creation, publication conflict refusal and invalid-intent refusal before native reads. Failing-before regressions cover the original source-correction failure, duplicate inspection, untrusted runtime selection and unconfigured consumer activation. Dedicated native adapter regressions reject either pinned ref moving during inspection. Normal commit hooks repeat full build, Jest and lint.

The automatic preflight token has read-only repository permissions; the existing product token supplies native reads and no new agent capabilities. This change does not deploy a consumer, publish a version or claim live adoption. The SDD and operator documentation include compatible-runtime/workflow setup, complete project verifier requirements, exact dispatch inputs, interrupted preparation and replay recovery.

Closes #732.

[docs-page]

To preview the documentation for this pull request, visit the following URL:

docs.page/vypdev/copilot~755

Documentation is deployed and generated using docs.page

[vypbot]

Current status: All findings originating in this review are resolved.
Last reconciled on e4273e1. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit 43a1b70 was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• low: Recovery performs the same full native inspection twice — src/application/usecases/actions/deployment_handlers/replace_candidate_handler.ts:38

[vypbot]

Bugbot: review complete

Current status: No active findings on e4273e1.

Pull request · Verified commit · Workflow run

[vypbot]

Copilot approval · Human review needed

Status: A protected workflow, policy, or trust-boundary file changed.
Completed: 1/1 observed checks succeeded; Bugbot complete.
Action required: Ask a human reviewer to decide.
Impact: No new approval is confirmed for this revision.
See checks

Technical evidence

Revision: e4273e1ebc3a; base: a34daa5bbdb7; reason: protected-path.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.78%. Comparing base (5b3664f) to head (e4273e1).
⚠️ Report is 29 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #755      +/-   ##
===========================================
+ Coverage    94.50%   94.78%   +0.28%     
===========================================
  Files         1035     1078      +43     
  Lines        33299    34856    +1557     
  Branches      9824    10354     +530     
===========================================
+ Hits         31468    33040    +1572     
+ Misses         699      684      -15     
  Partials      1132     1132              

Files with missing lines	Coverage Δ
deployment-recovery/index.cjs	100.00% <100.00%> (ø)
extension/tooling/package_contract.mts	100.00% <100.00%> (ø)
...c/actions/deployment_candidate_preflight_action.ts	100.00% <100.00%> (ø)
src/actions/github_action_execution.ts	94.73% <100.00%> (+0.98%)	⬆️
src/application/contracts/input_keys.ts	100.00% <ø> (ø)
...ies/deployment_candidate_preflight_presentation.ts	100.00% <100.00%> (ø)
...application/policies/deployment_message_catalog.ts	100.00% <ø> (ø)
...ication/policies/deployment_presentation_policy.ts	99.33% <100.00%> (+0.02%)	⬆️
...application/policies/local_single_action_policy.ts	100.00% <ø> (ø)
src/application/policies/setup_runner_policy.ts	100.00% <100.00%> (ø)
... and 16 more

... and 24 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vypbot]

Current status: All findings originating in this review are resolved.
Last reconciled on e4273e1. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 2 potential problems when commit 37143dd was analyzed. This snapshot is historical; use the status block above for current state. 2 findings are linked to changed code.

Findings

• high: Candidate preflight executes code from the supplied source SHA — .github/workflows/release_workflow.yml:128
• medium: Replacement mode always fails fresh verification — setup/workflows/release_workflow.yml:168

[vypbot]

Current status: All findings originating in this review are resolved.
Last reconciled on e4273e1. See aggregate Bugbot status.

🤖 Bugbot review snapshot

Bugbot reported 1 potential problem when commit 47cd2d3 was analyzed. This snapshot is historical; use the status block above for current state. 1 finding is linked to changed code.

Findings

• low: Preflight links the reviewed source as a prepared candidate — src/application/policies/deployment_candidate_preflight_presentation.ts:25