Merge pull request #166 from nikhil1/release/skill-1.3.0

feat(aws-transform): continuous-modernization updates

Author: nadetastic

aws-transform/POWER.md

@@ -4,7 +4,7 @@ displayName: "AWS Transform"
 description: "Migrate, modernize, and upgrade codebases: .NET Framework to .NET 8/10, mainframe COBOL to Java, VMware VMs to EC2, SQL Server/Oracle/MySQL to Aurora, and Java/Python/Node.js version upgrades or AWS SDK migrations. Assess, plan, and execute code transformations from your IDE."
 keywords: ["migrate", "modernize", "mainframe", "cobol", "vmware", "dotnet", ".net framework", "windows", "sql server", "oracle", "mysql", "aurora", "ec2 migration", "rehost", "lift-and-shift", "replatform", "legacy", "code upgrade", "sdk migration", "boto3", "java upgrade", "atx", "continuous modernization", "AWS Transform - continuous modernization"]
 author: "AWS"
-version: "2.2.0"
+version: "2.3.0"
 ---
 
 # AWS Transform Power

aws-transform/steering/workload-continuous-modernization-analysis.md

@@ -33,15 +33,21 @@ If the user explicitly asks to disable telemetry, omit `--telemetry` for the res
 - **EC2** -- follow [continuous-modernization-ec2-execution](workload-continuous-modernization-ec2-execution.md)
 - **Batch** -- follow [continuous-modernization-batch-execution](workload-continuous-modernization-batch-execution.md)
 
+## Repository limit per request (max 250)
+
+A single `atx ct analysis run` can be associated with at most **250 repositories**. Before starting an analysis that targets many repos (for example a whole source), check how many repositories are in scope — `atx ct source list` or `atx ct repository list --source <name>` report the per-source count. (Bare `atx ct status` shows workspace-wide totals across all sources, so prefer a scoped form when the analysis targets a single source.)
+
+If the scope exceeds 250 repositories, split it into multiple runs, each targeting at most 250 repos (pass the repos in batches via `--repo <source>::<slug>`), and tell the user you are breaking the work up because of the 250-repo-per-request limit. Never issue a single run associated with more than 250 repositories — it will be rejected. Example: 300 repos → two runs (250 + 50); 600 repos → three runs (250 + 250 + 100).
+
 ## Commands
 
 ```bash
-# Run analysis (returns immediately with analysis ID)
-atx ct analysis run --type <tech-debt-quick|tech-debt-comprehensive|security|agentic-readiness|modernization-readiness|custom> --source <name> [--repo <source>::<slug>] --telemetry "agent=<AGENT>,executionMode=local"
-
-# Run and wait for completion
+# Run analysis. Pass --wait so the command blocks until the run finishes (preferred — see "Running long analyses" below).
 atx ct analysis run --type <tech-debt-quick|tech-debt-comprehensive|security|agentic-readiness|modernization-readiness|custom> --source <name> [--repo <source>::<slug>] --wait --telemetry "agent=<AGENT>,executionMode=local"
 
+# --wait is only in newer CLI versions. If it isn't supported, run the same command without --wait.
+atx ct analysis run --type <tech-debt-quick|tech-debt-comprehensive|security|agentic-readiness|modernization-readiness|custom> --source <name> [--repo <source>::<slug>] --telemetry "agent=<AGENT>,executionMode=local"
+
 # Run custom analysis with a specific transformation definition
 atx ct analysis run --type custom --transformation-name <TD-name> --source <name> --repo <source>::<slug> --wait --telemetry "agent=<AGENT>,executionMode=local"
 
@@ -67,6 +73,21 @@ atx ct analysis cancel --id <id>
 atx ct analysis delete --id <id> [--cascade-findings]
 ```
 
+## Running long analyses (--wait, background, logs)
+
+`atx ct analysis run` returns immediately by default with an analysis ID. With `--wait` it blocks until the run completes — and a comprehensive or multi-repo run can take a long time. Prefer `--wait` so the run blocks to completion and you can act on the result in the same step.
+
+**`--wait` is version-gated.** It exists only in newer CLI versions. Before relying on it, confirm the installed CLI supports it — check `atx ct analysis run --help` (or `atx ct --version`). If `--wait` isn't listed, run the command without it; do not invent the flag. If a run fails with an unknown-option error for `--wait`, re-run without it.
+
+**Run long jobs in the background and monitor a log.** A blocking run ties up the session, so start long-running analyses in the background with `&`, redirect output to a log file, and monitor the log:
+
+```bash
+atx ct analysis run --type tech-debt-comprehensive --source <name> --wait --telemetry "agent=<AGENT>,executionMode=local" > /tmp/atx-analysis.log 2>&1 &
+tail -f /tmp/atx-analysis.log
+```
+
+This applies to comprehensive scans, large multi-repo runs, and any analysis the user expects to take a while. Tell the user where the log is and how to check progress.
+
 ## Custom Analysis
 
 The `custom` type runs any transformation definition (TD) against a repository. Unlike other analysis types, custom analysis does not generate findings -- it executes the TD directly.
@@ -198,3 +219,7 @@ If an analysis returns 0 findings on a repo that's obviously stale (Java 8, Node
 `--category` is a client-side grouping; e.g. `"Tech Debt"` matches both `tech-debt-quick` and `tech-debt-comprehensive`. Use it when the user wants both subtypes together.
 
 `--status` and `--type` accept only the canonical values above. Off-canonical input (e.g. `--status completed`, `--type tech-debt`) returns an `INVALID_INPUT` error.
+
+### Pagination (nextToken)
+
+Depending on the CLI version, `atx ct analysis list` may return only a bounded page rather than every result — don't assume a fixed response shape. After each call, check whether the response carries a `nextToken`; if it's present and non-empty, call the command again with `--next-token <token>` and repeat until no `nextToken` remains. Never treat the first page as the complete set when a `nextToken` is present, or you'll silently miss analyses.

aws-transform/steering/workload-continuous-modernization-findings.md

@@ -49,6 +49,20 @@ atx ct findings batch-update --ids <id1,id2,...> --status <open|dismissed> --rea
 atx ct findings delete --id <finding-id>
 ```
 
+## Pagination (nextToken)
+
+Depending on the CLI version, `atx ct findings list` may return only a bounded page rather than every finding — so don't assume a fixed response shape. After each call, check whether the response carries a `nextToken`. If it's present and non-empty, the results are truncated: call the same command again with the same filters plus `--next-token <token>`, and repeat until the response has no `nextToken`. Concatenate the pages before answering. If there's no `nextToken`, you already have the full set.
+
+```bash
+# First page
+atx ct findings list --status open --json
+# ...response includes "nextToken": "<token>" → fetch the next page
+atx ct findings list --status open --json --next-token <token>
+# ...repeat until the response has no nextToken
+```
+
+Never present the first page as the complete set when a `nextToken` is present — that silently drops findings and undercounts severity totals.
+
 ## Status set
 
 `open`, `dismissed`, `obsolete`. Transitions a user can drive: `open ↔ dismissed`. `obsolete` is a terminal state set by the system when a re-analysis no longer produces the finding — users do not transition into or out of it.
@@ -75,6 +89,7 @@ Filtering at the CLI is materially faster than pulling everything and filtering
 - "Auto-fixable" without a transform name → narrow with `--type tech-debt-quick` first. `tech-debt-quick` findings carry an ATX-transform fix; `security` findings carry a security-agent fix (see the [remediation](workload-continuous-modernization-remediation.md) skill). Findings without a `fix` field may still be remediable — see the [remediation](workload-continuous-modernization-remediation.md) skill's decision tree.
 - `--type` alone or `--type --severity`/`--type --min-severity` (no status, no repo) → add `--status open` to anchor on the live-triage shape.
 - Passing both `--severity` and `--min-severity` in the same call → the CLI rejects this. Pick one.
+- Treating the first page of `atx ct findings list` as the complete set when the response carries a non-empty `nextToken`. Page through with `--next-token <token>` until no `nextToken` remains — otherwise you silently drop findings.
 
 ### Multi-repo, multi-type questions
 

aws-transform/steering/workload-continuous-modernization-remediation.md

@@ -27,8 +27,9 @@ Format: `--telemetry "agent=<agent>,executionMode=<mode>"`
 If the user explicitly asks to disable telemetry, omit `--telemetry` for the rest of the session.
 
 ```bash
-# Create from finding IDs (uses each finding's fix.transform_name)
-atx ct remediation create --ids <id1,id2> --name "Fix name" --telemetry "agent=<AGENT>,executionMode=local"
+# Create from finding IDs (uses each finding's fix.transform_name).
+# Pass --wait so the command blocks until the remediation finishes (version-gated — see "Running long remediations" below).
+atx ct remediation create --ids <id1,id2> --name "Fix name" --wait --telemetry "agent=<AGENT>,executionMode=local"
 
 # Create from finding IDs with a custom TD override (ignores finding's fix field)
 atx ct remediation create --ids <id1,id2> --transformation-name <TD-name> --telemetry "agent=<AGENT>,executionMode=local"
@@ -55,6 +56,31 @@ atx ct remediation retry --id <id>
 atx ct remediation delete --id <id>
 ```
 
+## Repository limit per request (max 250)
+
+A single `atx ct remediation create` can be associated with at most **250 repositories**. Before creating a remediation that spans many repos, check how many distinct repositories the target findings cover.
+
+If the remediation would span more than 250 repositories, split it into multiple `remediation create` requests, each covering findings from at most 250 repos, and tell the user you are breaking it up because of the 250-repo-per-request limit. Never create a single remediation associated with more than 250 repositories — it will be rejected. Example: findings across 300 repos → two remediations (one for 250 repos, one for the remaining 50).
+
+## Running long remediations (--wait, background, logs)
+
+`atx ct remediation create` returns immediately by default with a remediation ID. With `--wait` it blocks until the remediation completes — and applying transforms across repos can take a long time. Prefer `--wait` so you can act on the result in the same step.
+
+**`--wait` is version-gated** — it exists only in newer CLI versions. Confirm support via `atx ct remediation create --help` (or `atx ct --version`) before relying on it; if it isn't listed, run without `--wait` and do not invent the flag. If a run fails with an unknown-option error for `--wait`, re-run without it.
+
+**Run long jobs in the background and monitor a log.** Start long-running remediations with `&`, redirect output to a log file, and monitor it:
+
+```bash
+atx ct remediation create --ids <id1,id2> --name "Fix name" --wait --telemetry "agent=<AGENT>,executionMode=local" > /tmp/atx-remediation.log 2>&1 &
+tail -f /tmp/atx-remediation.log
+```
+
+Tell the user where the log is and how to check progress.
+
+## Listing remediations (pagination)
+
+Depending on the CLI version, `atx ct remediation list` may return only a bounded page — don't assume a fixed response shape. After each call, if the response carries a non-empty `nextToken`, call the command again with `--next-token <token>` and repeat until no `nextToken` remains. Don't treat the first page as complete when a `nextToken` is present.
+
 ## Security Remediation
 
 Security findings (from `atx ct analysis run --type security`) are auto-remediable with the **same** `remediation create` command as any other finding — no `--transformation-name` is needed. Security findings carry a `security-agent` fix, which routes to the AWS Security Agent code-remediation API instead of an ATX transform; the fix is generated server-side.

aws-transform/steering/workload-continuous-modernization-reporting.md

@@ -26,9 +26,13 @@ atx ct findings list --json
 atx ct remediation list --json
 ```
 
+### Paginate every list to completion (nextToken)
+
+Response shape can vary by CLI version, so don't hard-code it: a list command may return every result at once, a bare array, or an object that wraps the array alongside a top-level `nextToken`. The report is a **static snapshot baked from this data**, so a dropped page silently loses sources, repos, analyses, findings, or remediations. The version-agnostic rule: after each list call, check whether the response carries a non-empty `nextToken`; if it does, call the command again with `--next-token <token>` and repeat until no `nextToken` remains, then concatenate all pages before normalizing. If there is no `nextToken`, the single response is already complete. A truncated `findings` or `remediation` fetch skews every KPI and chart downstream.
+
 ### Raw response shapes
 
-The five commands do NOT return the same envelope. Read each carefully — `repository list` wraps results in `{"items": [...]}`; the other four return a flat array. All field names are snake_case.
+The five commands do NOT return the same envelope, and the exact container can vary by CLI version — `repository list` wraps results in `{"items": [...]}`, while the others may come back as a bare array or (on newer CLIs) an object wrapping the array alongside a `nextToken` (see the pagination note above). Read the records wherever they live and follow `nextToken` when it's present. The shapes below describe the objects **inside** each list. All field names are snake_case.
 
 **`source list --json`** → flat array:
 ```jsonc

aws-transform/steering/workload-continuous-modernization-source.md

@@ -118,6 +118,10 @@ atx ct repository update --source <source> --labels "migration:v2"
 atx ct repository delete --repo "<source>::<slug>" --source <source>
 ```
 
+## Pagination (nextToken)
+
+Depending on the CLI version, `atx ct source list` and `atx ct repository list` may return only a bounded page — don't assume a fixed response shape. After each call, if the response carries a non-empty `nextToken`, call the command again with `--next-token <token>` (keeping any `--source`/`--labels` filters) and repeat until no `nextToken` remains. Don't treat the first page as the complete set — otherwise sources or repos silently go missing from listings and downstream scoping.
+
 ## Labels
 
 Labels are user-defined identifiers for organizing and filtering groups of repositories.