fix: defer deployment issue completion until publication and reconciliation

docs/guides/releases-and-hotfixes.mdx

@@ -44,6 +44,21 @@ Check the durable operation and publication facts together:
 
 A merged production PR, closed issue, created tag or successful preparation job alone does not establish all of these facts.
 
+Production promotion is an intermediate milestone. The launcher remains open
+and below 100% while protected publication, reconciliation or cleanup is pending.
+Copilot detaches the promotion PR's native closing relationship to its launcher
+before handing it to the configured merge policy. If a run reports a remaining
+closing reference, inspect that PR's closing keywords and Development links and
+use the existing recovery action.
+
+After verified publication, reconciliation and cleanup, Copilot records functional
+completion before closing the launcher and verifying its progress metadata and
+existing status cards. If only this final issue projection fails, the failed Job
+Summary remains actionable and retains the verified publication facts. Retry the
+failed publication-completion job; it finishes the issue projection without
+republishing or repeating completed cleanup. A configured keep-open launcher
+remains open.
+
 ## Hotfixes and recovery
 
 For a hotfix, use the installed **Hotfix** form with an existing Base Version tag and the new Hotfix Version, description and solution. Start with `in-progress`, wait for readiness, then explicitly launch with `deploy`. Its origin is the selected production tag; reconciliation follows the configured development/active-release policy.

docs/issues/notifications-and-auto-close.mdx

@@ -225,3 +225,13 @@ successful label repair does not conceal a failed card retirement. Inspect the
 named failure and current issue, resolve the access/evidence conflict, then
 retry the actual closed-issue or merged-PR operation only if cleanup is still
 required for that same closure. Keep reopened work open.
+
+## Deployment launcher completion
+
+A Release or Hotfix operation stays pending through production promotion. Its
+launcher closes and reaches 100% only after verified publication, all required
+reconciliation and cleanup. Native PR/branch linkage is not completion evidence.
+Closed-event metadata and recommendation retirement defer when fresh durable
+state still identifies a pending deployment. An already closed historical
+launcher is retained for inspection; no automatic reopen authority is added.
+See the [release and hotfix guide](/guides/releases-and-hotfixes#verify-completion).

scripts/coverage-budgets.json

@@ -1236,6 +1236,44 @@
         }
       ],
       "successMessage": "branch sync catalog coverage: PASS (closed classification100%; adapters/recovery95/90)"
+    },
+    {
+      "name": "Deferred native deployment issue completion",
+      "missingEntryLabel": "deployment issue completion",
+      "rules": [
+        {
+          "files": [
+            "src/domain/deployment_issue_completion.ts",
+            "src/domain/issue_completion.ts",
+            "src/application/usecases/actions/deferred_deployment_completion.ts"
+          ],
+          "mode": "each",
+          "thresholdProfile": "exhaustive"
+        },
+        {
+          "files": [
+            "src/data/repository/deployment/github_deployment_issue_completion.ts",
+            "src/data/repository/deployment/github_managed_pull_request_repository.ts",
+            "src/data/repository/issue/issue_completion_repository.ts",
+            "src/application/services/deployment_merge_effects.ts",
+            "src/application/usecases/actions/deployment_handlers/reconciliation_handler.ts",
+            "src/application/usecases/actions/deployment_handlers/confirm_publication_handler.ts",
+            "src/application/usecases/actions/reconcile_closed_issue_metadata_use_case.ts",
+            "src/application/usecases/actions/retire_branch_sync_use_case.ts",
+            "src/application/usecases/actions/retire_progress_use_case.ts",
+            "src/application/usecases/steps/issue/close_issue_after_merging_use_case.ts",
+            "src/application/policies/closed_issue_reconciliation_outcome_policy.ts",
+            "src/application/usecases/push_single_action_contexts.ts",
+            "src/infrastructure/composition/main_run_route_composition_root.ts",
+            "src/infrastructure/composition/push_single_action_capability_port_binding.ts",
+            "src/actions/github_action_completion.ts",
+            "src/application/policies/deployment_presentation_policy.ts"
+          ],
+          "mode": "each",
+          "thresholdProfile": "default"
+        }
+      ],
+      "successMessage": "deferred native deployment completion: PASS (pure 100%; changed modules 95% lines/statements, 90% branches/functions)"
     }
   ]
 }

specs/catalog.json

@@ -390,7 +390,7 @@
       "status": "implemented",
       "scope": "Release and hotfix promotion, publication, bounded merge readiness recovery, and receipt-verified reconciliation without republication; explicit native-guarded replacement of closed unpublished candidates with complete fresh validation and bounded audit history",
       "owner": "Copilot maintainers",
-      "lastVerified": "2026-10-28",
+      "lastVerified": "2026-10-30",
       "specs": [
         "specs/configurable-release-orchestration.md",
         "specs/configurable-release-orchestration-traceability.md",
@@ -450,7 +450,10 @@
         "src/application/policies/deployment_candidate_preflight_presentation.ts",
         "deployment-recovery/action.yml",
         "deployment-recovery/index.cjs",
-        "scripts/deployment-replacement-contract.cjs"
+        "scripts/deployment-replacement-contract.cjs",
+        "src/domain/deployment_issue_completion.ts",
+        "src/data/repository/deployment/github_deployment_issue_completion.ts",
+        "src/application/usecases/actions/deferred_deployment_completion.ts"
       ],
       "tests": [
         "src/domain/__tests__/deployment_operation.test.ts",
@@ -482,7 +485,10 @@
         "src/actions/__tests__/deployment_candidate_declared_inputs.test.ts",
         "src/actions/__tests__/deployment_candidate_preflight_action.test.ts",
         "src/tooling/__tests__/deployment_replacement_workflows.test.ts",
-        "src/application/usecases/execution/__tests__/single_action_target_restore.integration.test.ts"
+        "src/application/usecases/execution/__tests__/single_action_target_restore.integration.test.ts",
+        "src/domain/__tests__/deployment_issue_completion.test.ts",
+        "src/data/repository/deployment/__tests__/github_deployment_issue_completion.test.ts",
+        "src/application/usecases/actions/__tests__/deployment_issue_completion.integration.test.ts"
       ],
       "documentation": [
         "docs/issues/deployment-orchestration.mdx",
@@ -1844,7 +1850,7 @@
       "status": "as-built-baseline",
       "scope": "Convert typed issues into traceable work branches, project state, and lifecycle state",
       "owner": "Copilot maintainers",
-      "lastVerified": "2026-10-20",
+      "lastVerified": "2026-10-30",
       "specs": [
         "specs/managed-issue-and-branch-lifecycle.md"
       ],
@@ -1892,7 +1898,9 @@
         "src/application/errors/closed_issue_reconciliation_error.ts",
         "src/application/usecases/actions/reconcile_issue_completion_metadata.ts",
         "src/application/usecases/actions/verify_closed_issue_card_retirement.ts",
-        "src/application/policies/closed_issue_reconciliation_outcome_policy.ts"
+        "src/application/policies/closed_issue_reconciliation_outcome_policy.ts",
+        "src/domain/deployment_issue_completion.ts",
+        "src/application/usecases/actions/deferred_deployment_completion.ts"
       ],
       "tests": [
         "src/application/usecases/__tests__/issue_pull_request_context_projection.test.ts",
@@ -1919,7 +1927,9 @@
         "src/application/usecases/actions/__tests__/reconcile_closed_issue_metadata_use_case.test.ts",
         "src/application/usecases/actions/__tests__/reconcile_closed_issue_use_case.test.ts",
         "src/application/errors/__tests__/closed_issue_reconciliation_error.test.ts",
-        "src/application/policies/__tests__/closed_issue_reconciliation_summary.test.ts"
+        "src/application/policies/__tests__/closed_issue_reconciliation_summary.test.ts",
+        "src/domain/__tests__/deployment_issue_completion.test.ts",
+        "src/application/usecases/actions/__tests__/deployment_issue_completion.integration.test.ts"
       ],
       "documentation": [
         "docs/issues/branch-management.mdx",

specs/configurable-release-orchestration-traceability.md

@@ -168,3 +168,17 @@ selection and disabled-by-default consumer replacement. Native adapter cases
 exercise source/base drift after inventory without duplicating whole inspections.
 Current-head PR evidence supersedes earlier local baseline counts; no unsafe ACL
 or verification exception is introduced to make platform CI green.
+
+## Native launcher completion boundary (#792)
+
+| Requirement | Implementation / evidence |
+|---|---|
+| Prevent linked-branch promotion auto-close before handler | `github_deployment_issue_completion.ts`; stateful `deployment_issue_completion.integration.test.ts` uses actual linked-branch and managed-PR adapters |
+| Exact owned native unlink and verified absence | 200-reference bounded adapter tests, exact PR/issue/repository/head/operation checks; existing expected-head native merge/queue pins |
+| Pending state cannot produce generic completion | `deployment_issue_completion.ts`, native issue facts adapter, issue completion policy, generic close/metadata/card tests |
+| Complete functional plan before close callback | reconciliation handler persists completed after cleanup and before issue closure; strict finalization ordering test |
+| Retry issue projection without repeating irreversible effects | trusted publication handler, completion failure/replay cases, en-US/es-ES and actual Action Job Summary tests |
+
+These are deterministic regression and source/API-schema evidence, not a claim
+of a live consumer release, package upload, tag, automatic promotion or visual
+GitHub acceptance. Preserve the existing live-evidence gates above.

specs/configurable-release-orchestration.md

@@ -1905,3 +1905,92 @@ No deployment, package retry, manual release or new permission is authorized by
 this diagnostic. The complete flow, compatibility, recovery UI and exclusive
 32-case budget are specified in
 [CLI and single-action execution](./cli-and-single-action-execution.md#explicit-action-target-restoration--740-2026-10-28).
+
+## 24. Deferred native issue completion (#792, 2026-10-30)
+
+The existing contract that promotion must not close its launcher includes GitHub's
+native relationship, not only PR text. Release/hotfix preparation calls
+`createLinkedBranch(issue)`. GitHub automatically associates the subsequent PR
+with that issue, so a default-branch merge can close it before any PR-closed
+handler even when the body has no closing keyword. This mechanism is documented
+by [GitHub branch creation](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/creating-a-branch-for-an-issue)
+and [linked PR closure](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
+The report's private timeline is supplied evidence; it has not been independently
+read. A generic temporary-reference probe does not establish its exact producer.
+
+```mermaid
+flowchart LR
+  A[Linked release branch] --> B[Native promotion PR association]
+  B --> C[Verify owner and remove only launcher closing reference]
+  C --> D[Verify reference absent and use configured native merge policy]
+  D --> E[Verified publication and all reconciliation]
+  E --> F[Cleanup and persist completed state]
+  F --> G[Native issue completion and metadata]
+```
+
+Before configured merge, auto-merge, queue or create-only handoff, verify the
+native repository, PR/issue IDs, managed operation/phase, branches and frozen head.
+Use GitHub's `removeCloseIssueReferences` only for this launcher and managed PR;
+never alter repository auto-close settings or delete a branch. Verify that the
+closing relationship is absent afterwards. The current host's schema was checked
+read-only; [the documented mutation](https://docs.github.com/en/graphql/reference/issues)
+does not remove body-keyword references. Missing support, unreadable/changed
+identity, a failed mutation or a remaining relationship blocks merge setup with
+existing semantic diagnostics and an instruction to inspect closing references.
+Retain all required checks, environment review and expected-head pins. At most
+one reference-removal mutation and two pages of 100 closing references per
+attempt; the existing one merge-readiness recovery remains the retry bound.
+Separate provider calls are observations, not atomic compare-and-swap.
+
+Fresh native completion facts must identify a validated durable deployment that
+has not completed. Generic merged-PR closure, closed-issue progress metadata and
+recommendation retirement must defer for it. Native closure alone is not evidence
+of publication or reconciliation. Malformed/unsupported durable state cannot be
+downgraded to ordinary completion. Preserve ordinary completed, duplicate and
+not-planned issue handling and configured keep-open behavior. Do not infer a
+new native reopen authority from a historical premature close; retain that fact
+and explain deferred completion rather than claiming repair.
+
+Final completion requires verified publication and its immutable receipt, all
+configured reconciliation and successful cleanup. Persist completed functional
+state before the final issue close so its native callback observes the correct
+boundary. Supported replay must finish any remaining issue projection without
+republishing, changing operation identity or repeating completed cleanup. A
+projection failure retains completed irreversible effects and reports a truthful,
+retryable result. No new public input, schema, provider permission or rollout is
+introduced. A rollback may restore the old premature relationship behavior for
+new promotions; finish active plans with the corrected runtime.
+
+Representative pending UI remains: `Release 3.4.0 — publishing artifacts`, with
+production accepted, publication/reconciliation/cleanup unchecked and the launcher
+open below 100%. Only the complete configured plan may produce closed/100%.
+Existing dashboard, result steps and Job Summary carry deferred/error guidance;
+no routine additional comment or notification is introduced. Update the release
+guide, catalog/traceability and generated bundles with this implementation.
+
+Reserve **at least 39 distinct new cases before implementation**:
+
+| Area | Minimum | Required behavior |
+|---|---:|---|
+| Pure completion policy | 10 | pending phases, verified completion, incomplete publication/targets, unknown state, ordinary completion |
+| Native PR relationship adapter | 10 | exact owned unlink, retained keyword reference, identity changes, provider failures, response/pagination bounds and idempotence |
+| Native issue facts adapter | 4 | valid pending/completed state, ordinary metadata and malformed durable state |
+| Application and finalization | 8 | deferred generic close/labels/cards, cleanup failure, completion-before-close ordering, projection retry and keep-open |
+| Stateful causal integration | 4 | actual linked-branch/PR producer, pre-handler provider auto-close, queued/failed publication and ordinary-control preservation |
+| Completion Job Summary | 3 | failed native projection remains actionable in en-US/es-ES and the real Action summary, while functional completion facts remain immutable |
+| **Total** | **39** | no double counting; record additional distinct acceptance extensions |
+
+Use owned deterministic provider fixtures, with event-order assertions before the
+closed handler. No real tag, package upload, release, environment bypass or private
+consumer execution is part of regression verification. Keep existing timeouts,
+global/module floors, architecture and setup ledger. New pure policy requires
+100% all metrics; changed adapters/application modules require at least 95%
+lines/statements and 90% branches/functions, plus exact added runtime lines 100%.
+Fresh CI/native Linux/macOS/Windows acceptance, deferred cleanup, coverage and
+complete zero-active-findings review remain merge gates. Run specification,
+workflow/documentation validators, package smoke and the AST graph update.
+
+The completion Job Summary must show a failed, retryable native issue projection
+even when functional state is already `completed`. This is transient result
+evidence, never a rewrite of persisted completion/publication facts. Reserve the
+three presentation/Action cases above before implementing this projection.

specs/deployment-concurrency-and-state-fencing.md

@@ -568,3 +568,16 @@ The existing monotonic-successor regression now includes such quoted text and
 verifies its preservation. Operation/revision fences, workflow serialization,
 publication receipts and issue completion behavior are unchanged by this
 classification correction. No deployment is performed for this regression.
+
+## Functional completion before native issue projection (#792)
+
+After verified publication, all configured reconciliation and cleanup, persist
+the completed operation through the existing revision fence before final native
+issue closure. This prevents its close callback from observing an unfinished
+plan. Native issue projection failure retains that completed functional snapshot,
+operation ID and immutable receipts; it does not move completed state backwards
+or republish. A trusted publication-completion replay revalidates the external
+receipt, skips completed cleanup and retries only native closure/metadata/cards.
+The failed result and Job Summary identify pending projection independently of
+functional phase. No new stored field, version, lock or provider permission is
+introduced. The release SDD section24 owns the additional cases.

specs/managed-issue-and-branch-lifecycle.md

@@ -856,3 +856,22 @@ workflows/specifications/catalogs, generated bundles, Graphify and current-head
 CI/review. Review the English/Spanish summary examples for readable status and
 one next action. Production convergence is not claimed until a fresh promoted
 consumer sequence verifies its native issue and required cleanup.
+
+## Typed deployment completion exception (#792, 2026-10-30)
+
+The native-close contract above continues for ordinary issues. Fresh bounded
+issue facts additionally classify an owned valid deployment operation. Pending
+publication, reconciliation or cleanup defers generic closure, 100%/lifecycle
+cleanup and existing-card retirement, even if an earlier runtime already closed
+the native issue. Unavailable, ambiguous or unsupported owned durable state
+cannot certify ordinary completion. No close/reopen authority is added to the
+metadata or card ports. The existing per-write native fences also reject a
+concurrent pending operation. Deferred results have a distinct machine outcome
+and do not advertise closed cleanup convergence.
+
+The release owner's [section 24](./configurable-release-orchestration.md#24-deferred-native-issue-completion-792-2026-10-30)
+owns the additional numeric budget and native linked-branch/PR causal evidence;
+do not double count it against this SDD. Final orchestration reuses these same
+scoped reconciliation capabilities after its functional completion checkpoint.
+Ordinary completed/not-planned/duplicate handling, selective label preservation,
+card bounds, exact witnesses and cancellation behavior remain required.