Source

This page is generated from skills/ecs-modernize/references/deploy-verify-handoff.md. Edit the source, not this page.

Module: Deploy, Verify and Handoff

Part of: ecs-modernize Purpose: Close out Migration_Execution: hand off the Rearchitect compute models to ecs-build with a traceable name/value input list, run terraform apply only behind the destroy check and the user's confirmation, verify that every ECS service the apply created or updated reaches steady state using read-only APIs only — and own the Execution_Log rules that every execution module of this skill records against Prerequisites: Execution_Gate passage (Requirement 14) + availability of the environment Terraform — the ecs-build output for a Rearchitect compute model, the Replatform_Environment_Terraform generated per replatform-environment-build.md, or the Windows_Environment_Terraform generated per windows-environment-build.md

This module is the final stage of Migration_Execution. It has four responsibilities: (1) for Rearchitect compute models, present the structured handoff that delegates environment IaC generation to ecs-build and detailed design to ecs-architect; (2) apply the environment Terraform — gated by the pre-apply destroy check and the terraform apply action-class confirmation — or, when the user declines, enable them to apply it themselves; (3) verify steady state for all services the apply touched, with strictly read-only ECS APIs; (4) define the Execution_Log recording rules for the whole skill — code-transformation.md, containerization-execution.md, replatform-environment-build.md, and windows-environment-build.md all record their actions per the rules in this file.

Which paths hand off and which do not. The handoff below applies to the Rearchitect compute models (Express Mode, Fargate, Managed Instances) only. The Replatform path and the Windows_Container_Path are generated inside this skill, because ecs-build does not cover their shape — see the coverage table in SKILL.md. For those two, skip the handoff section and proceed directly to the Deploy Procedure with the generated Terraform directory.

This module is ECS-specific: it depends on the ECS resource model (services, task definitions, deployments) and the ECS steady-state verification APIs.

Table of Contents

• Inputs
• Rearchitect Compute-Model Handoff
• Deploy Procedure
• Steady-State Verification
• Determination Criteria
• Execution_Log Rules
• Output Schema
• Edge Cases

---

Inputs

• Execution_Gate passage (required) — the gate's two conditions hold. This module never runs before the gate.
• Environment Terraform (required for deploy and verification) — one of:
  • the ecs-build output for an approved Rearchitect compute model (Express Mode / Fargate / Managed Instances), or
  • the Replatform_Environment_Terraform generated by replatform-environment-build.md for an approved Linux Replatform path (ECS on EC2, bridge, sticky sessions), or
  • the Windows_Environment_Terraform generated by windows-environment-build.md for the Windows_Container_Path. The handoff portion of this module can run before the Terraform exists — its purpose is to produce the inputs ecs-build needs — and it applies to the Rearchitect compute models only.
• Containerization execution results (Requirement 16 outputs) — the generated Containerization_Artifact files (Dockerfile, task-definition input values) and the push result (the full image URI), from containerization-execution.md. These are the source of truth for image URI, exposed ports, and health check values in the handoff.
• Source_Analysis findings (when the assessment ran) — Blocker detection results and Replatform/Rearchitect path outputs. These are the source of truth for volume/EFS needs (local-filesystem-write findings) and session affinity needs (in-process session state Blockers).
• Action-class confirmation state — the terraform apply action class of Requirement 14 gates the apply. Its confirmation presents the Terraform directory to be applied; if that directory changes after confirmation, re-obtain the confirmation before applying.

---

Rearchitect Compute-Model Handoff

When the approved target path is a Rearchitect compute model (ECS Express Mode, Fargate, or Managed Instances), this skill does not generate the environment IaC. Instead:

• Environment IaC generation is delegated to ecs-build — state the delegation by name and hand over the input list below. Never generate Rearchitect compute-model environment Terraform in this skill, neither in the answer nor in the Modernization_Report.
• Detailed target design is delegated to ecs-architect — capacity-provider strategy, task sizing, and network design are named as ecs-architect's scope; this skill does not produce those design values.

Handoff format — name/value list

Present the handoff as a list that pairs each item name with its value. The six items below are mandatory; add further items only when a concrete migration finding requires them.

Item	Value source (traceability)
Image URI	The full URI reported by the Requirement 16 push result (containerization_execution.push.image_uri)
Exposed ports	The port(s) declared in the generated Containerization_Artifact (Dockerfile EXPOSE / task-definition input values) — Requirement 16 outputs
Health check	The health check defined in the Containerization_Artifact task-definition input values (Requirement 16); where the assessment identified an app-provided health endpoint, cite that Source_Analysis finding
Resource sizing inputs	The CPU/memory input values from the Containerization_Artifact task-definition inputs (Requirement 16), grounded in Source_Analysis evidence where it exists (e.g. runtime and framework footprint)
Volume / EFS needs	Source_Analysis local-filesystem-write findings and the Replatform path's persistent-vs-temporary classification: name each write target classified as persistent and the mount policy it received
Session affinity needs	Source_Analysis in-process session state Blocker (present → affinity required, cite the Blocker id; absent → not required, cite the absence)

Traceability rule (Requirement 17.6): every value in the handoff is reported together with its origin — the Requirement 16 artifact or push result it came from, and/or the Source_Analysis finding that grounds it. A value with no traceable origin does not go into the handoff as a settled value.

Unresolved items: when an item's value is not yet settled (e.g. the image was not pushed, or sizing evidence is missing), do NOT invent a value. Record the item as unresolved and state, in place of the value, the condition required to settle it — for example: "Image URI: unresolved — settles when the Requirement 16 remote build (CodeBuild Windows path does not apply here; local build failed) is completed and the image is pushed to ECR". Unresolved items stay in the list; they are never silently dropped.

---

Deploy Procedure

Run the steps in this order. Every step's attempt is recorded per the Execution_Log Rules before the next step begins.

1. Pre-apply destroy check      -> terraform plan; any delete action against an
                                   existing AWS resource blocks the apply
2. Apply confirmation           -> the `terraform apply` action class (Req 14),
                                   presenting the Terraform directory
3a. Confirmed  -> run apply     -> report success/failure and created resources
3b. Declined   -> hand over     -> present the exact commands and working
                                   directory; do NOT apply on the user's behalf
4. Steady-state verification    -> only after a confirmed successful apply
                                   (skill-run success or user-declared completion)

Step 1 — Pre-apply destroy check

Before any terraform apply, run terraform plan in the target Terraform directory and inspect the plan for delete/destroy actions against existing AWS resources.

• One or more delete actions present → do NOT execute the apply. Report the full list of existing resources planned for deletion (resource type and identifier for each) to the user. The apply does not proceed under this plan.
• Zero delete actions → the apply MAY proceed — after, and only after, the Step 2 confirmation.

This check is mandatory before every apply, including re-applies after a plan change: a changed plan gets a fresh destroy check.

Step 2 — Apply confirmation

Obtain the terraform apply action-class confirmation (Requirement 14), presenting the Terraform directory to be applied. An ambiguous response is not a confirmation — re-present and ask for an unambiguous answer. If the target directory changed since a prior confirmation, re-obtain the confirmation with the changed content.

Step 3a — Confirmed: run the apply

Run terraform apply and report the outcome:

• Success — report success and the resources the apply created (and updated), from the Terraform output.
• Failure — report the failure and the error content from the Terraform output. Do NOT start steady-state verification, and do NOT claim the environment application succeeded (see Edge Cases).

Step 3b — Declined: enable manual apply

When the user does not approve the skill running terraform apply:

• Present the procedure for the user to apply it themselves — at minimum the commands (terraform plan for their own review, then terraform apply) and the working directory in which to run them.
• Do NOT run the apply on the user's behalf. The declined class stays unexecuted until the user either re-confirms it or reports that they applied it themselves (which is the entry point for verification below).

---

Steady-State Verification

Verification starts when the environment application is confirmed complete — either the skill-run terraform apply succeeded, or the user declared that they completed the apply themselves.

Scope

The verification target is every ECS service that the apply created or updated — no sampling, no "the main service only". Determine the set from the apply output (skill-run apply) or from the Terraform configuration and the user's declaration (manual apply).

Read-only API rule

Use only ECS API operations whose names start with Describe or List — e.g. DescribeServices, DescribeTasks, ListTasks, DescribeTaskDefinition. No other operation is permitted during verification, regardless of how harmless it is. Verification never creates, modifies, or deletes anything.

Polling window

• Start: the point at which the apply completion was confirmed.
• Duration: at most 10 minutes from that start point.
• Interval: successive checks of the same service are spaced at least 15 seconds apart.

Steady-state predicate

A service has reached steady state if and only if BOTH hold at the same observation:

1. Running task count equals desired task count (runningCount == desiredCount from DescribeServices), AND
2. The most recent deployment is in a completed state (the latest deployment's rollout state is completed — e.g. rolloutState: COMPLETED — with no in-progress replacement).

Never report "steady state reached" for a service on any weaker evidence.

Verification report

When verification ends — whether every service reached steady state or not — report:

• The items checked (running vs. desired task counts, latest deployment status, and any stopped-task / service-event data gathered),
• The API operations used (the exact operation names),
• The per-service outcome — reached / not reached, with the observed counts and deployment state for each service.

Timeout diagnosis (read-only)

If any target service has not reached steady state when the 10-minute window closes:

• Gather diagnostic information with the same read-only rule: stopped task stop reasons (ListTasks with desiredStatus: STOPPED + DescribeTasks → stoppedReason) and service events (DescribeServices → events).
• Report the plausible causes grounded in that data (e.g. image pull failure, failing health checks, insufficient capacity).
• Do NOT claim the verification succeeded.
• Do NOT create or modify any AWS resource to fix the problem without a new user confirmation — the earlier apply confirmation does not cover remediation changes.

---

Determination Criteria

Decision	Criterion
Apply may proceed	terraform plan contains zero delete actions against existing AWS resources, AND the terraform apply action-class confirmation is complete for the current target directory
Apply is blocked	The plan contains one or more delete actions against existing AWS resources → never apply; report the deletion list. (This restates the skill-wide rails of Requirements 11.10 / 11.15 as this module's hard predicate)
Verification may start	The apply completion is confirmed: skill-run terraform apply succeeded, OR the user declared they completed the apply. A failed skill-run apply never starts verification
Steady state reached (per service)	running count == desired count AND the latest deployment is completed — both observed together
Verification API is permissible	The operation name starts with Describe or List. Anything else is not used
Handoff value is settled	The value traces to a Requirement 16 output (artifact / push result) and/or a Source_Analysis finding. Otherwise the item is unresolved with its settling condition stated

---

Execution_Log Rules

Canonical section. These rules govern the Execution_Log for all Migration_Execution actions across this skill — file generation, AWS Transform job starts, image builds and pushes, ECR repository creation, Terraform generation and application, and this module's own actions. The other execution modules (code-transformation.md, containerization-execution.md, windows-environment-build.md) reference this section rather than restating it.

Recording rule

Every attempted action is recorded — success or failure alike — before the next action starts. Recording is a per-action discipline, not an end-of-run summary: an action that fails is logged with its failure before anything else is attempted, so an interruption at any point leaves a complete record of everything tried up to it.

Required fields per entry

Each Execution_Log entry carries at least:

Field	Content
Action type	What was attempted (e.g. terraform_plan, terraform_apply, image_push, ecr_repository_create, file_generation, transform_job_start, steady_state_check)
Result	success or failure
Created / modified targets	The applicable identifiers among: repository, branch, file paths, AWS resource identifiers
Timestamp	The execution date-time in a timezone-identifiable format (e.g. ISO 8601 with offset: 2025-07-25T20:53:11+09:00)
User confirmation	Whether a corresponding user confirmation existed for the action

Storage forms

When Migration_Execution completes or is interrupted, save the Execution_Log using exactly one of these forms, then report the chosen form and the save location to the user:

1. Append to the Modernization_Report — the log becomes a section of the existing report, or
2. Sibling file — a separate file placed in the same directory as the Modernization_Report and referenced from the report, or
3. Standalone file — when no Modernization_Report exists (the assessment was skipped per Requirement 14), save the log as an independent file outside the target source code directory, and report that location.

Save-failure fallback

If saving the Execution_Log fails, report that the save failed and why, do NOT claim the log was saved, and present the full Execution_Log content in the conversation so the record is not lost.

---

Output Schema

This module produces the deployment_verification and execution_log blocks (plus environment_construction.handoff_items when the Rearchitect compute-model handoff runs). Hold the structures in conversation context; the durable record is the saved Execution_Log.

environment_construction:            # Rearchitect compute models only — the ecs-build handoff
  path: linux
  handoff_items:
    - name: string                   # e.g. "Image URI", "Exposed ports", "Session affinity"
      value: string | unresolved     # the settled value, or the unresolved marker
      unresolved_condition: string | null   # what settles the item (unresolved only)
      traceability: string           # the Req 16 output and/or Source_Analysis finding behind the value

deployment_verification:
  applied_by: skill | user           # skill-run apply, or user-declared apply completion
  plan_destroy_check:
    delete_actions: [string]         # existing resources planned for deletion (empty = check passed)
    apply_blocked: bool              # true whenever delete_actions is non-empty
  apply_result: success | failed | null   # null when the user declined and has not applied yet
  services:
    - name: string
      steady_state: reached | not_reached
      running_vs_desired: string     # e.g. "2/2"
      deployment_status: string      # latest deployment rollout state
  polling: {max_minutes: 10, min_interval_seconds: 15}
  api_operations_used: [string]      # exact operation names, all Describe*/List*
  diagnosis: [string]                # read-only findings on not_reached (stop reasons, service events)

execution_log:
  entries:
    - action_type: string
      result: success | failure
      targets: {repo: string, branch: string, paths: [string], aws_resource_ids: [string]}
      timestamp_tz: string           # timezone-identifiable, e.g. ISO 8601 with offset
      user_confirmation: bool
  save:
    form: report_append | sibling_file | standalone_file
    location: string

Reporting invariants:

• apply_blocked: true and a non-null apply_result never coexist for the same plan — a blocked plan is not applied.
• services entries exist only after verification started; a failed apply_result forbids verification entirely.
• Every steady_state: reached entry shows running == desired AND a completed deployment.
• Every operation in api_operations_used starts with Describe or List.
• Every handoff item is either settled-with-traceability or unresolved with an unresolved_condition — never a bare guess.
• The execution_log.entries sequence is append-ordered: entry n was recorded before action n+1 began.

---

Edge Cases

The skill-run terraform apply fails

Report the failure and the error content from the Terraform output. Do NOT start steady-state verification, and do NOT claim the environment application succeeded. Log the failed apply per the recording rule, then present options (fix the configuration and re-plan — the fresh plan gets a fresh destroy check — or hand over to manual investigation).

A service never reaches steady state within 10 minutes

Follow the timeout diagnosis: read-only data gathering, a grounded causal report, no success claim, and no remediation writes without a new user confirmation. The verification report still lists every service with its per-service outcome — partial success (some reached, some not) is reported per service, never rolled up into a blanket claim.

The user declares the apply complete without the skill running it

The declaration is the verification entry point (applied_by: user). Determine the service set from the Terraform configuration and the user's statement; if the set cannot be determined, ask the user to name the created/updated services rather than guessing. Verification then proceeds under the same rules.

The plan contains delete actions on a re-apply

The destroy check applies to every plan, not just the first: report the deletion list and block the apply, even if an earlier plan for the same directory was clean.

The apply creates no ECS services

If the apply touched no ECS service (e.g. an infrastructure-only layer), report that there is no verification target and why — do not fabricate a steady-state claim, and do not verify unrelated pre-existing services.

No Modernization_Report exists at log-save time

The assessment was skipped, so form 3 (standalone file) applies: save the Execution_Log outside the target source directory and report the location. Never write the log into the target source tree.

Saving the Execution_Log fails

Apply the save-failure fallback: report the failure and reason, make no save claim, and output the full log content in the conversation.

Handoff requested before containerization finished

Produce the handoff with the settled items filled and the rest marked unresolved with their settling conditions (typically "complete the Requirement 16 build/push"). The handoff is not blocked by unresolved items — ecs-build delegation guidance and the traceable partial list still go out.

Migration_Execution is interrupted mid-module

The recording rule has already captured every attempted action. Save the log per the storage forms (interruption triggers the save just as completion does), report the chosen form and location, and report which deploy/verification steps completed and which did not.