[aem-cloud-service] Fix replication contracts, launcher events, workflow endpoints, and runtime guidance

Start by reading the listed replication, workflow-launcher, and workflow-foundation files, then inspect the analyzer and migration-validator scripts and their existing fixtures. Check each correction against the primary sources and record the SDK version used; add focused checks for the event constants, workflow endpoints, and replication behavior. Done means all twelve fixes have evidence-backed verification, with live-environment checks explicitly marked unverified when unavailable.

Scope

Consolidate the verified AEM as a Cloud Service correctness fixes from the external AEM skills review. Evidence was checked against repository commit 8f35e907 on 2026-10-27 and the primary sources below.

This is a defect-remediation issue, not the proposed new-skills/agents backlog. AEM 6.5 LTS fixes belong in #495. README corrections belong in #496; cross-runtime structuring belongs in #497. EDS and project-management automation concerns are explicitly deferred by the requester.

Required fixes

CS-01. Stop treating supported Replicator usage as an invalid migration

code-assessment/replication/SKILL.md says com.day.cq.replication.Replicator is unsupported and removed from the Cloud SDK. The analyzer flags its import, and the migration validator fails any bundle importing com.day.cq.replication. These rules contradict both Adobe's current product documentation and this plugin's own content-distribution/replication skill.

The existing fixture reproduces the false positive:

bash plugins/aem/cloud-service/skills/code-assessment/scripts/analyze.sh \
  plugins/aem/cloud-service/test/code-assessment/fixtures/replication \
  --pattern replication

It reports LegacyReplicator.java even though its replicate(Session, ReplicationActionType, String) call uses the supported API.

• Correct the unsupported/removed claims and remove the unconditional requirement to rewrite CQ Replicator to Distributor.
• Align the detector, migration validator, resolution contracts, troubleshooting, and existing fixture expectations with the supported API contract.
• Add regression cases proving supported Replicator code and bundle imports are accepted. Retain separately justified detection of genuinely unsupported APIs; do not disable the entire pattern.
• Preserve the behavior of valid publishing code rather than changing APIs solely to satisfy the old detector.

Relevant files:

• plugins/aem/cloud-service/skills/code-assessment/scripts/analyzer/detectors/Replication.java
• plugins/aem/cloud-service/skills/code-assessment/replication/SKILL.md
• plugins/aem/cloud-service/skills/migration/scripts/validate-migration/check/patterns/replication.js
• plugins/aem/cloud-service/test/code-assessment/fixtures/replication/
• plugins/aem/cloud-service/test/code-assessment/run-tests.sh

CS-02. Correct publish/preview routing semantics

The code-assessment guide says the legacy Replicator implicitly fans out to every configured agent. Cloud Service uses the default publish agent for an unfiltered call; preview requires explicit filtering.

• Distinguish Cloud Service defaults from legacy 6.x agent configurations.
• Keep publish-only, preview-only, and both-tier examples consistent with that distinction.

CS-03. Fix the non-compiling listener example

content-distribution/replication/SKILL.md:218-237 omits the required first Agent parameter from onStart, onEnd, and onError.

• Correct the three signatures and necessary imports.
• Compile the runnable example against an explicitly recorded supported aem-sdk-api version.
• Preserve the existing synchronous-only warning at line 250. The external review incorrectly reported this warning as absent in Cloud Service.

CS-04. Reconcile bulk limits without inventing a resolution

The skill promises automatic splitting above 100 paths with no options and says not to call setUseAtomicCalls. Experience League recommends approximately 100 paths, documents a 500-path limit and ReplicationException above it, and describes setUseAtomicCalls(false) as an alternative. The checked 2026.9 SDK Javadoc still marks that option deprecated; this conflict is not confined to the stale Javadoc from 2022.

• Record the target SDK and source versions and reconcile the supported behavior.
• Remove the unconditional "no options needed" guarantee while the conflict is unresolved.
• Keep custom calls conservatively bounded to approximately 100 paths, handle/report ReplicationException, and prefer Tree Activation for large trees.
• Distinguish compile-time API/deprecation checks from runtime batch-limit verification. Compilation alone does not establish server-side limits or atomicity.

CS-05. Make publication status agent-specific where required

The status helpers use aggregate isActivated() without explaining that preview-only publication can leave it false.

• Keep live-publish status and preview status distinct.
• Use getStatusForAgent("preview") for preview checks and include an example where preview is activated but aggregate status is false.

CS-06. Correct workflow-launcher event constants and dependent examples

Both aem-workflow/workflow-launchers/SKILL.md:42 and its references/workflow-launchers/condition-patterns.md mislabel JCR event values. For example, 2 means node removal, not node modification.

Verified JCR values:

Constant	Value
NODE_ADDED	1
NODE_REMOVED	2
PROPERTY_ADDED	4
PROPERTY_REMOVED	8
PROPERTY_CHANGED	16
NODE_MOVED	32
PERSIST	64

• Correct the table, single-event examples, combined-event explanations, and every dependent "on edit" recommendation in the Cloud workflow tree.
• Do not present NODE_MODIFIED as a JCR Event constant.
• Add a focused regression check for the constants and affected edit/delete examples.

CS-07. Correct all stale workflow-start endpoints

Four aem-workflow/*/references/workflow-foundation/quick-start-guide.md copies POST to /api/workflow/instances; only the workflow-triggering copy uses /var/workflow/instances.

• Fix all four executable examples, not just the entry-point guide.
• Add a check preventing the incorrect POST examples from returning. Retain intentional negative examples that explain why the old endpoint is wrong.
• Coordinate with the separate structuring issue for canonical shared references.

CS-08. Correct Cloud queue monitoring and delivery guidance

content-distribution/replication/SKILL.md:564-569 directs users to a hosted Cloud author's /system/console/slingjobs. The supported operational entry point is Tools > Deployment > Distribution, then the publish/preview agent's status, queues, and logs.

code-assessment/replication/SKILL.md:682,731 describes persisted and fully published as successive item states. Current product documentation describes two queues, with different completion guarantees.

• Replace the hosted-Felix troubleshooting path with supported Cloud monitoring instructions.
• Explain the two queues accurately: persisted content versus content live across publish pods with Dispatcher invalidation complete.
• Distinguish request acceptance, persistence, and full publication; do not claim a queued response proves delivery.
• Reconcile the existing queue guidance across both skill families rather than adding a second contradictory explanation.

CS-09. Replace stale API citations with versioned verification evidence

The Cloud tree has 13 links to the old Adobe-hosted Cloud Javadoc; inspected replication pages identify SDK 2022.11.9850.20221116T162329Z-220900. The current product page points to SDK Javadoc on javadoc.io.

• Update affected API citations to an appropriate versioned source and record the SDK actually checked.
• Verify the API claims, not merely that the new URLs resolve.
• Do not assume changing the host resolves the bulk-limit conflict in CS-04.

CS-10. Replace positive production examples that write to standard output

content-distribution/replication/SKILL.md:331-336 uses System.out.println in a positive status example.

• Use SLF4J consistently in the affected positive Java examples.
• Preserve deliberately labelled legacy/negative examples where standard output is part of the demonstrated problem.

CS-11. Make local-only credentials and mutation examples unambiguous

Workflow quick starts contain admin:admin for localhost. The copied Oak reference also uses default credentials with generic {host}:{port} targets and direct index writes. These must not be read as instructions for hosted Cloud environments.

• Explicitly constrain default local credentials and direct repository/index experiments to an isolated local SDK.
• Use the supported authentication and deployment route for hosted Cloud examples; do not suggest direct hosted /oak:index writes.
• Preserve intentional negative examples: the asset-manager admin:admin snippet is explicitly marked WRONG, not a recommendation or leaked credential.

CS-12. State what happens when Dispatcher MCP is unavailable

The Dispatcher entry point requires the Cloud MCP variant but does not state an explicit unavailable-tool response.

• State the required mode and missing prerequisite clearly.
• Allow bounded explanation/static review where supported, while marking MCP-dependent checks blocked or not verified.
• Never claim runtime validation, fabricate tool output, or silently apply a different runtime's instructions.
• Do not require a new MCP implementation or a new general-purpose agent for this fix.

Regression and completion criteria

• Every required fix above has an implemented change and an evidence-backed verification result.
• Existing analyzer and migration-validator tests no longer encode supported Replicator usage as an error.
• Add focused content checks for launcher constants, bad workflow-start POST examples, and the corrected local/hosted boundary.
• Add a repeatable compile check for the corrected runnable positive Java examples. Explicitly classify fragments/placeholders and intentional negative examples rather than blindly compiling every Markdown fence.
• State which assertions require a live environment and report them as unverified when no such environment is available.
• Preserve beta markers and keep directly dependent references and call sites consistent.

Review reconciliation / exclusions

This issue covers external-review items I-01-I-06, I-08-I-10, I-26, I-29, the corrective portion of I-13, Cloud portions of I-23/I-28, and focused regression protection related to I-27. I-11 is not a Cloud defect because the synchronous-only warning already exists.

Missing standalone skills/agents, full per-skill eval infrastructure, preferred-invalidation coverage (I-12), and scheduled-publishing coverage (I-14) remain enhancements, not hidden blockers for this defect issue. Naming, nesting, runtime guards, reference ownership, and shared-skill packaging belong in #497. README/metadata corrections belong in #496. Cross-plugin items I-31-I-34 (EDS/project-management and the unrelated web CLI fallback) are outside this runtime issue and remain deferred.

Primary sources

• Cloud Service replication, routing, status, capacity and queues
• SDK 2026.9 ReplicationListener
• SDK 2026.9 ReplicationOptions
• SDK 2026.9 Replicator
• JCR Event constants