From a2997ac16edf0c1de62da1fc290afb0b9e25880d Mon Sep 17 00:00:00 2001
From: Luke Parrott <lparrott@salesforce.com>
Date: Mon, 17 Nov 2025 15:51:46 -0600
Subject: [PATCH 1/7] Updating trial org shape to latest template

---
 orgs/trial.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/orgs/trial.json b/orgs/trial.json
index 318526bb920..2d345538e3a 100644
--- a/orgs/trial.json
+++ b/orgs/trial.json
@@ -1,6 +1,6 @@
 {
   "orgName": "NPSP - Trial Org",
-  "template": "0TT8a000002mZLJ",
+  "template": "0TTHp00000AQMxK",
   "settings": {
     "chatterSettings": {
       "enableChatter": true

From 69602fe0aa45976b6a37b6f28ec4bbce0d7f93f8 Mon Sep 17 00:00:00 2001
From: Michael Smith <SmithMichael@Salesforce.com>
Date: Sun, 10 May 2026 14:30:58 -0700
Subject: [PATCH 2/7] address issues with announcing setup sidebar items with
 state (#7323)

---
 .../accordionSection/accordionSection.html    |  8 +-
 .../lwc/accordionSection/accordionSection.js  | 18 ++++
 .../default/pages/STG_SettingsManager.page    | 92 +++++++++++--------
 3 files changed, 78 insertions(+), 40 deletions(-)

diff --git a/force-app/main/default/lwc/accordionSection/accordionSection.html b/force-app/main/default/lwc/accordionSection/accordionSection.html
index d632b5ed601..41c45c7c426 100644
--- a/force-app/main/default/lwc/accordionSection/accordionSection.html
+++ b/force-app/main/default/lwc/accordionSection/accordionSection.html
@@ -10,15 +10,16 @@
                     class="slds-align_absolute-center slds-m-vertical_x-small"
                 >
                     <button
-                        aria-label={title}
+                        aria-label={buttonAriaLabel}
                         onclick={handleToggle}
                         aria-controls="accordion-details"
-                        aria-expanded={isOpen}
+                        aria-expanded={ariaExpanded}
                         class="slds-align-middle slds-text-link_reset slds-button"
                     >
                         <lightning-icon
                             icon-name={toggleIcon}
                             alternative-text={toggleInstructions}
+                            aria-hidden="true"
                             size="x-small"
                         ></lightning-icon>
                     </button>
@@ -27,6 +28,9 @@
                 <!--CLICKABLE SECTION-->
                 <lightning-layout-item
                     onclick={handleToggle}
+                    onkeydown={handleClickableKeydown}
+                    role="button"
+                    tabindex="0"
                     flexibility="auto"
                     class="slds-grid_vertical-align-center clickable-header"
                 >
diff --git a/force-app/main/default/lwc/accordionSection/accordionSection.js b/force-app/main/default/lwc/accordionSection/accordionSection.js
index 5106dc28750..a46dc000e35 100644
--- a/force-app/main/default/lwc/accordionSection/accordionSection.js
+++ b/force-app/main/default/lwc/accordionSection/accordionSection.js
@@ -25,6 +25,15 @@ export default class AccordionSection extends LightningElement {
         return this.isOpen ? toggleInstructionsWhenOpen : toggleInstructionsWhenClosed;
     }
 
+    get ariaExpanded() {
+        return this.isOpen ? "true" : "false";
+    }
+
+    get buttonAriaLabel() {
+        const state = this.isOpen ? "expanded" : "collapsed";
+        return `${this.title}, ${state}`;
+    }
+
     get classes() {
         let classes = ["slds-accordion__section"];
 
@@ -47,6 +56,15 @@ export default class AccordionSection extends LightningElement {
 
     handleToggle() {
         this.toggle();
+        // eslint-disable-next-line @lwc/lwc/no-async-operation
+        setTimeout(() => this.template.querySelector("button")?.focus(), 0);
+    }
+
+    handleClickableKeydown(event) {
+        if (event.key === "Enter" || event.key === " ") {
+            event.preventDefault();
+            this.handleToggle();
+        }
     }
 
     @api
diff --git a/force-app/main/default/pages/STG_SettingsManager.page b/force-app/main/default/pages/STG_SettingsManager.page
index 2c9022b904d..bae297de168 100644
--- a/force-app/main/default/pages/STG_SettingsManager.page
+++ b/force-app/main/default/pages/STG_SettingsManager.page
@@ -19,11 +19,11 @@
         box-shadow: none;
     }
 
-    div.slds-tree__item button.chevronright, div.slds-tree__item.collapsed button.chevrondown {
+    div.slds-tree__item button .chevronright, div.slds-tree__item.collapsed button .chevrondown {
         display: none;
     }
 
-    div.slds-tree__item button.chevrondown, div.slds-tree__item.collapsed button.chevronright {
+    div.slds-tree__item button .chevrondown, div.slds-tree__item.collapsed button .chevronright {
         display: inline-block;
     }
 
@@ -52,11 +52,21 @@
     if (idPanelCurrent == '') idPanelCurrent = 'idPanelHome';
 
     // page init function
+    function syncAriaExpanded() {
+        j$('#mynavbar .slds-tree__branch button[aria-expanded]').each(function() {
+            var isCollapsed = j$(this).closest('.slds-tree__branch').hasClass('collapsed');
+            j$(this).attr('aria-expanded', isCollapsed ? 'false' : 'true');
+        });
+    }
+
     j$(function () {
         var cl = j$('#mynavbar').collapsibleList('.slds-tree__branch', {search: false, animate: false});
         // start with slds-tree-container all collapsed.  couldn't figure out how to call collapseAllHeaders(),
         // but submitting the click on all li's does the trick!
         j$('div',cl).trigger('click');
+        j$('#mynavbar .slds-tree__branch').on('click', function() {
+            syncAriaExpanded();
+        });
         ShowPanel(idPanelCurrent);
     });
 
@@ -131,13 +141,14 @@
                         <ul id="mynavbar" class="slds-tree slds-list_vertical slds-has-block-links-space" role="tree" aria-labelledby="treeheading" aria-activedescendant="tree0-node0" >
                             <!-- People -->
                             <div class="slds-tree__branch slds-tree__item" id="idPanelConHomeNav">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavPeople}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelConHomeNavGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <a id="tree0-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavPeople}</a>
+                                <a id="tree0-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavPeople}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree0-node0-link">
                                 <li class="slds-tree__item" role="treeitem" aria-level="2" id="idPanelConNav"><a href="#" onclick="ShowPanel('idPanelCon');return false;" class="slds-grow slds-m-left_large">{!$Label.stgNavAccountModel}</a></li>
@@ -147,13 +158,14 @@
                             </ul>
                             <!-- Relationships -->
                             <div class="slds-tree__branch slds-tree__item" id="idPanelConnectionsNav">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavRelationships}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelConnectionsNavGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <a id="tree1-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavRelationships}</a>
+                                <a id="tree1-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavRelationships}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree1-node0-link">
                                 <li class="slds-tree__item" role="treeitem" aria-level="2" id="idPanelAfflNav"><a href="#" onclick="ShowPanel('idPanelAffl');return false;" class="slds-grow slds-m-left_large">{!$Label.stgNavAffiliations}</a></li>
@@ -163,13 +175,14 @@
                             </ul>
                             <!-- Donations -->
                             <div class="slds-tree__branch slds-tree__item" id="idPanelDonationsNav">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavDonations}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelDonationsNavGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <a id="tree2-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavDonations}</a>
+                                <a id="tree2-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavDonations}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree2-node0-link" >
                                 <li class="slds-tree__item" role="treeitem" aria-level="2" id="idPanelOppNamingNav"><a href="#" onclick="ShowPanel('idPanelOppNaming');return false;" class="slds-grow slds-m-left_large">{!$Label.stgLabelOppNamingSettings}</a></li>
@@ -188,13 +201,14 @@
                             <!-- Recurring Donations -->
 
                             <div class="slds-tree__branch slds-tree__item" id="idPanelRecDonationsNav">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavRecurringDonations}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelRecDonationsNavGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <a id="tree3-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavRecurringDonations}</a>
+                                <a id="tree3-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavRecurringDonations}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree3-node0-link">
                                 <li role="treeitem" aria-level="2" id="idPanelRD2EnablementNav"
@@ -247,13 +261,14 @@
 
                             <!-- Bulk Data Processes -->
                             <div class="slds-tree__branch slds-tree__item" id="idPanelBulkProcesses">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavBulkProcesses}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelBulkProcessesGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <a id="tree4-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavBulkProcesses}</a>
+                                <a id="tree4-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavBulkProcesses}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree4-node0-link">
                                 <li class="slds-tree__item" role="treeitem" aria-level="2" id="idPanelScheduleNav"><a href="#" onclick="ShowPanel('idPanelSchedule');return false;" class="slds-grow slds-m-left_large">{!$Label.stgNavBatchProcessSettings}</a></li>
@@ -270,13 +285,14 @@
                             </ul>
                             <!-- System Tools -->
                             <div class="slds-tree__branch slds-tree__item" id="idPanelSystemNav">
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevronright">
-                                    <c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" />
-                                </button>
-                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small chevrondown">
-                                    <c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" />
+                                <button class="slds-button slds-button_icon-bare slds-m-right_x-small"
+                                    aria-label="{!$Label.stgNavSystem}"
+                                    aria-expanded="false"
+                                    aria-controls="idPanelSystemNavGroup">
+                                    <span class="chevronright"><c:UTIL_SLDS_Icon icon="chevronright" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
+                                    <span class="chevrondown"><c:UTIL_SLDS_Icon icon="chevrondown" iconCategory="utility" size="xx-small" fillColor="inherit" /></span>
                                 </button>
-                                <a id="tree5-node0-link" tabindex="-1" role="presentation">{!$Label.stgNavSystem}</a>
+                                <a id="tree5-node0-link" aria-hidden="true" tabindex="-1">{!$Label.stgNavSystem}</a>
                             </div>
                             <ul class="slds-tree__group slds-nested" role="group" aria-labelledby="tree5-node0-link">
                                 <li class="slds-tree__item" role="treeitem" aria-level="2" id="idPanelHealthCheckNav"><a href="#" onclick="ShowPanel('idPanelHealthCheck');return false;" class="slds-grow slds-m-left_large">{!$Label.stgNavHealthCheck}</a></li>

From cd6f3d27d79e3c0910cc551dbbfeafc0b27e6934 Mon Sep 17 00:00:00 2001
From: Andrew Yu <andrew.yu@salesforce.com>
Date: Wed, 6 May 2026 14:45:39 -0700
Subject: [PATCH 3/7] Add regression tests for W-19306508 monthly RD next
 donation date skip bug (TDD)

Tests verify that monthly RDs with DayOfMonth=31/30/Last_Day starting in
short months (Feb/Apr/Jun) do not skip the current 31-day month when
calculating next donation date. Covers unit, integration, and batch paths.
---
 .../RD2_OpportunityEvaluationService_TEST.cls |  35 ++++
 .../RD2_OpportunityEvaluation_TEST.cls        |  44 +++++
 .../classes/RD2_ScheduleService_TEST.cls      | 167 ++++++++++++++++++
 3 files changed, 246 insertions(+)

diff --git a/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls b/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
index 41b8262c642..8ff92fb2f74 100644
--- a/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
+++ b/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
@@ -2350,6 +2350,41 @@ private class RD2_OpportunityEvaluationService_TEST {
             'The non matching installment opportunity should stay open');
     }
 
+    /***
+    * @description Verifies that when a monthly RD with DayOfMonth=31 starts in a short month
+    * (February), the created Installment Opportunity has the correct CloseDate in the current
+    * 31-day month rather than skipping to the next month.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldCreateOppWithCorrectCloseDateWhenDayOfMonth31AndStartInFeb() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        final Date today = Date.newInstance(2021, 7, 29);
+        final Date expectedCloseDate = Date.newInstance(2021, 7, 31);
+
+        RD2_ScheduleService.currentDate = today;
+        RD2_EnablementService_TEST.setRecurringDonations2Enabled();
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationBuilder(getContact())
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .withCalculateNextDonationDate()
+            .build();
+
+        Test.startTest();
+        insert rd;
+        Test.stopTest();
+
+        rd = rdGateway.getRecord(rd.Id);
+        List<Opportunity> opps = oppGateway.getRecords(rd);
+
+        System.assertEquals(1, opps.size(), 'One Installment Opp should be created');
+        System.assertEquals(expectedCloseDate, opps[0].CloseDate,
+            'Opp CloseDate should be July 31, not skip to August');
+        System.assertEquals(expectedCloseDate, rd.npe03__Next_Payment_Date__c,
+            'Next Payment Date should be July 31');
+    }
+
     // Helpers
     ///////////////////
 
diff --git a/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls b/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
index 954b96474bd..0a5ac7935ec 100644
--- a/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
+++ b/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
@@ -1355,6 +1355,50 @@ public with sharing class RD2_OpportunityEvaluation_TEST {
             'The batch should be set to Custom Setting Recurring_Donation_Batch_Size__c value');
     }
 
+    /***
+    * @description Verifies the batch job creates an Opp with correct CloseDate when
+    * DayOfMonth=31 (converted to Last_Day), StartDate is in February, and the batch
+    * runs on day 31 of a subsequent month. The next donation date should not skip a month.
+    * Regression test for W-19306508.
+    */
+    @IsTest
+    private static void shouldNotSkipMonthForNextOppWhenBatchRunsOnDay31WithFebStart() {
+        RD2_EnablementService_TEST.setRecurringDonations2Enabled();
+
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        RD2_ScheduleService.currentDate = startDate;
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .withCalculateNextDonationDate()
+            .build();
+        insert rd;
+
+        List<Opportunity> opps = oppGateway.getRecords(rd);
+        System.assertEquals(1, opps.size(), 'An Opp should be created on insert');
+        System.assertEquals(Date.newInstance(2021, 2, 28), opps[0].CloseDate,
+            'First Opp CloseDate should be Feb 28 (last day of Feb)');
+
+        final Date batchRunDate = Date.newInstance(2021, 7, 31);
+        RD2_ScheduleService.currentDate = batchRunDate;
+
+        runBatch(new RD2_OpportunityEvaluation_BATCH(batchRunDate));
+
+        assertBatchJobIteration(1);
+
+        rd = rdGateway.getRecord(rd.Id);
+        opps = oppGateway.getRecords(rd);
+
+        System.assertEquals(2, opps.size(), 'A second Opp should be created by the batch');
+
+        Opportunity newOpp = opps[0].CloseDate > opps[1].CloseDate ? opps[0] : opps[1];
+        System.assertEquals(batchRunDate, newOpp.CloseDate,
+            'New Opp CloseDate should be July 31, not skip to August 31');
+        System.assertEquals(batchRunDate, rd.npe03__Next_Payment_Date__c,
+            'Next Payment Date should be July 31');
+    }
+
     // Helpers
     //////////////
 
diff --git a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
index 2af0b82a2fb..004c8b81327 100644
--- a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
+++ b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
@@ -353,6 +353,173 @@ public with sharing class RD2_ScheduleService_TEST {
         System.assertEquals(nextDonationDate, service.getNextDonationDate(rd), 'Next Donation Date should match');
     }
 
+    /***
+    * @description Verifies next donation date is not skipped when DayOfMonth=31,
+    * StartDate is in February (28 days), and referenceDate is before end of target month.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipMonthWhenStartInFebAndDayOfMonth31() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 7, 29);
+        Date nextDonationDate = Date.newInstance(2021, 7, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 31, not skip to August');
+    }
+
+    /***
+    * @description Verifies next donation date when referenceDate equals the expected
+    * donation date (July 31) for a DayOfMonth=31 RD starting in February.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldReturnSameDateWhenRefDateEqualsDayOfMonth31() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 7, 31);
+        Date nextDonationDate = Date.newInstance(2021, 7, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 31 when referenceDate is July 31');
+    }
+
+    /***
+    * @description Verifies next donation date advances to next month when referenceDate
+    * is past the current month's donation date.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldAdvanceToNextMonthWhenRefDatePastDayOfMonth31() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 8, 1);
+        Date nextDonationDate = Date.newInstance(2021, 8, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be Aug 31 when referenceDate is Aug 1');
+    }
+
+    /***
+    * @description Verifies next donation date is not skipped when DayOfMonth=31 and
+    * StartDate is in April (30 days), and batch runs on last day of a 31-day month.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipMonthWhenStartInAprilAndDayOfMonth31() {
+        final Date startDate = Date.newInstance(2021, 4, 1);
+        Date today = Date.newInstance(2021, 7, 31);
+        Date nextDonationDate = Date.newInstance(2021, 7, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 31 when starting in April');
+    }
+
+    /***
+    * @description Verifies next donation date is not skipped when DayOfMonth=Last_Day and
+    * StartDate is in June (30 days), and batch runs on last day of a 31-day month.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipMonthWhenStartInJuneAndDayOfMonthLastDay() {
+        final Date startDate = Date.newInstance(2021, 6, 1);
+        Date today = Date.newInstance(2021, 7, 31);
+        Date nextDonationDate = Date.newInstance(2021, 7, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth(RD2_Constants.DAY_OF_MONTH_LAST_DAY)
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 31 when using Last_Day starting in June');
+    }
+
+    /***
+    * @description Verifies next donation date is not skipped when DayOfMonth=30 and
+    * StartDate is in February (28 days).
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipMonthWhenStartInFebAndDayOfMonth30() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 7, 29);
+        Date nextDonationDate = Date.newInstance(2021, 7, 30);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('30')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 30 when starting in Feb with DayOfMonth 30');
+    }
+
+    /***
+    * @description Verifies next donation date is not skipped when DayOfMonth=Last_Day and
+    * StartDate is in February.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipMonthWhenStartInFebAndDayOfMonthLastDay() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 7, 29);
+        Date nextDonationDate = Date.newInstance(2021, 7, 31);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth(RD2_Constants.DAY_OF_MONTH_LAST_DAY)
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be July 31 when using Last_Day starting in Feb');
+    }
+
+    /***
+    * @description Non-regression: Verifies normal DayOfMonth (15) is not affected by
+    * the fix for W-19306508. Day 15 never exceeds any month's length.
+    */
+    @isTest
+    private static void shouldNotAffectNormalDayOfMonth15WithFebStart() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        Date today = Date.newInstance(2021, 7, 20);
+        Date nextDonationDate = Date.newInstance(2021, 8, 15);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('15')
+            .build();
+
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(today);
+        System.assertEquals(nextDonationDate, service.getNextDonationDate(rd),
+            'Next Donation Date should be Aug 15 for normal DayOfMonth');
+    }
+
     /***
     * @description Verifies next donation date for monthly donation when donation falls in current month.
     */

From 7ab8ffca7ed80f8c7b0fa5106d9982ad757533f3 Mon Sep 17 00:00:00 2001
From: Andrew Yu <andrew.yu@salesforce.com>
Date: Wed, 6 May 2026 15:09:57 -0700
Subject: [PATCH 4/7] Add visualization and batch regression tests for
 W-19306508

Adds test for getVisualizedInstallments showing skipped installment when
viewed from a late day in the month (e.g., Mar 29 with Feb start DayOfMonth=31).
Also fixes April/June tests to use referenceDate=Jul 31 to actually trigger the bug.
---
 .../classes/RD2_ScheduleService_TEST.cls      | 38 +++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
index 004c8b81327..0814bcfc52f 100644
--- a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
+++ b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
@@ -1754,6 +1754,44 @@ public with sharing class RD2_ScheduleService_TEST {
         testAndAssertVisualizedInstallments(RD2_Constants.INSTALLMENT_PERIOD_MONTHLY, startDate, dayOfMonth, nextDonationDateByIndex);
     }
 
+    /***
+    * @description Verifies visualized installments are not skipped when DayOfMonth=31,
+    * StartDate is in February, and visualization starts from a late day in March.
+    * The first installment shown should be Mar 31, not skip to Apr 30.
+    * Regression test for W-19306508.
+    */
+    @isTest
+    private static void shouldNotSkipInstallmentInVisualizationWhenStartInFebAndViewedFromDay29() {
+        final Date startDate = Date.newInstance(2021, 2, 1);
+        final Date viewDate = Date.newInstance(2021, 3, 29);
+
+        RD2_EnablementService_TEST.setRecurringDonations2Enabled();
+        RD2_ScheduleService service = getScheduleServiceForCurrentDate(viewDate);
+
+        npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
+            .withStartDate(startDate)
+            .withDayOfMonth('31')
+            .build();
+
+        Test.startTest();
+        insert rd;
+        Test.stopTest();
+
+        List<RecurringDonationSchedule__c> schedules = new RD2_QueryService()
+            .getRecurringDonationsWithRelatedRecords(new Set<Id>{ rd.Id }, startDate)[0].RecurringDonationSchedules__r;
+
+        List<RD2_ScheduleService.Installment> installments = service.getVisualizedInstallments(
+            viewDate, 3, schedules);
+
+        System.assertEquals(3, installments.size(), 'Should return 3 installments');
+        System.assertEquals(Date.newInstance(2021, 3, 31), installments[0].nextDonationDate,
+            'First visualized installment should be March 31, not skip to April');
+        System.assertEquals(Date.newInstance(2021, 4, 30), installments[1].nextDonationDate,
+            'Second installment should be April 30');
+        System.assertEquals(Date.newInstance(2021, 5, 31), installments[2].nextDonationDate,
+            'Third installment should be May 31');
+    }
+
     /***
     * @description Verifies visualization works as expected across short month with day of month > days in short month
     */

From f22538d4849186d91cf093a1fe7e1cdbb19ee0f9 Mon Sep 17 00:00:00 2001
From: Andrew Yu <andrew.yu@salesforce.com>
Date: Wed, 6 May 2026 15:53:35 -0700
Subject: [PATCH 5/7] Fix monthly RD next donation date skipping month for
 short-month starts

Apply day-of-month correction before comparing against referenceDate so
the comparison uses the actual donation date (e.g., Jul 31) rather than
the clamped addMonths result (e.g., Jul 28). Extract adjustToTargetDayOfMonth
helper to avoid duplicating the correction logic.

W-19306508
---
 .../default/classes/RD2_ScheduleService.cls   | 38 ++++++++++++-------
 1 file changed, 24 insertions(+), 14 deletions(-)

diff --git a/force-app/main/default/classes/RD2_ScheduleService.cls b/force-app/main/default/classes/RD2_ScheduleService.cls
index d71d09c325e..a6bf3cb0c08 100644
--- a/force-app/main/default/classes/RD2_ScheduleService.cls
+++ b/force-app/main/default/classes/RD2_ScheduleService.cls
@@ -543,24 +543,16 @@ public without sharing class RD2_ScheduleService {
 
         Date adjusted = addDateUnits(firstValid, (unitsBetween / adjustedFrequency) * adjustedFrequency, schedule.InstallmentPeriod__c);
 
+        if (schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_MONTHLY && schedule.DayOfMonth__c != null) {
+            adjusted = adjustToTargetDayOfMonth(adjusted, schedule);
+        }
+
         if (adjusted < referenceDate) {
             adjusted = addDateUnits(adjusted, adjustedFrequency, schedule.InstallmentPeriod__c);
-        }
 
-        if (schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_MONTHLY) {
-            if (schedule.DayOfMonth__c == null) {
-                return adjusted;
-            }
-            Integer nextDayOfMonth;
-            if (schedule.DayOfMonth__c == RD2_Constants.DAY_OF_MONTH_LAST_DAY ||
-                Integer.valueOf(schedule.DayOfMonth__c) > Date.daysInMonth(adjusted.year(), adjusted.month()))
-            {
-                nextDayOfMonth = Date.daysInMonth(adjusted.year(),adjusted.month());
+            if (schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_MONTHLY && schedule.DayOfMonth__c != null) {
+                adjusted = adjustToTargetDayOfMonth(adjusted, schedule);
             }
-            else {
-                nextDayOfMonth = Integer.valueOf(schedule.DayOfMonth__c);
-            }
-            adjusted = Date.newInstance(adjusted.year(), adjusted.month(), nextDayOfMonth);
         }
 
         if (
@@ -620,6 +612,24 @@ public without sharing class RD2_ScheduleService {
         return adjustedDate;
     }
 
+    /***
+    * @description Adjusts a date to the target day of month for the schedule.
+    * @param adjusted Date to adjust
+    * @param schedule Recurring Donation Schedule record
+    * @return Date
+    */
+    private Date adjustToTargetDayOfMonth(Date adjusted, RecurringDonationSchedule__c schedule) {
+        Integer nextDayOfMonth;
+        if (schedule.DayOfMonth__c == RD2_Constants.DAY_OF_MONTH_LAST_DAY ||
+            Integer.valueOf(schedule.DayOfMonth__c) > Date.daysInMonth(adjusted.year(), adjusted.month()))
+        {
+            nextDayOfMonth = Date.daysInMonth(adjusted.year(), adjusted.month());
+        } else {
+            nextDayOfMonth = Integer.valueOf(schedule.DayOfMonth__c);
+        }
+        return Date.newInstance(adjusted.year(), adjusted.month(), nextDayOfMonth);
+    }
+
     /***
     * @description Calculates the earliest valid donation date based on start date.
     * @param schedule Recurring Donation Schedule record

From 98b0deda5aaadc5f4a2614cc2c5a22c0e56f52a5 Mon Sep 17 00:00:00 2001
From: Andrew Yu <andrew.yu@salesforce.com>
Date: Mon, 11 May 2026 10:17:25 -0700
Subject: [PATCH 6/7] Use DayOfMonth 30 instead of 31 in regression tests to
 avoid Last_Day restricted picklist error in scratch orgs

---
 .../RD2_OpportunityEvaluationService_TEST.cls | 12 +++++------
 .../RD2_OpportunityEvaluation_TEST.cls        | 21 ++++++++++---------
 .../classes/RD2_ScheduleService_TEST.cls      | 14 ++++++-------
 3 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls b/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
index 8ff92fb2f74..5a7d5b3fa25 100644
--- a/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
+++ b/force-app/main/default/classes/RD2_OpportunityEvaluationService_TEST.cls
@@ -2353,21 +2353,21 @@ private class RD2_OpportunityEvaluationService_TEST {
     /***
     * @description Verifies that when a monthly RD with DayOfMonth=31 starts in a short month
     * (February), the created Installment Opportunity has the correct CloseDate in the current
-    * 31-day month rather than skipping to the next month.
+    * month rather than skipping to the next month.
     * Regression test for W-19306508.
     */
     @isTest
-    private static void shouldCreateOppWithCorrectCloseDateWhenDayOfMonth31AndStartInFeb() {
+    private static void shouldCreateOppWithCorrectCloseDateWhenDayOfMonth30AndStartInFeb() {
         final Date startDate = Date.newInstance(2021, 2, 1);
         final Date today = Date.newInstance(2021, 7, 29);
-        final Date expectedCloseDate = Date.newInstance(2021, 7, 31);
+        final Date expectedCloseDate = Date.newInstance(2021, 7, 30);
 
         RD2_ScheduleService.currentDate = today;
         RD2_EnablementService_TEST.setRecurringDonations2Enabled();
 
         npe03__Recurring_Donation__c rd = getRecurringDonationBuilder(getContact())
             .withStartDate(startDate)
-            .withDayOfMonth('31')
+            .withDayOfMonth('30')
             .withCalculateNextDonationDate()
             .build();
 
@@ -2380,9 +2380,9 @@ private class RD2_OpportunityEvaluationService_TEST {
 
         System.assertEquals(1, opps.size(), 'One Installment Opp should be created');
         System.assertEquals(expectedCloseDate, opps[0].CloseDate,
-            'Opp CloseDate should be July 31, not skip to August');
+            'Opp CloseDate should be July 30, not skip to August');
         System.assertEquals(expectedCloseDate, rd.npe03__Next_Payment_Date__c,
-            'Next Payment Date should be July 31');
+            'Next Payment Date should be July 30');
     }
 
     // Helpers
diff --git a/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls b/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
index 0a5ac7935ec..2ba97a2b53d 100644
--- a/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
+++ b/force-app/main/default/classes/RD2_OpportunityEvaluation_TEST.cls
@@ -1357,12 +1357,12 @@ public with sharing class RD2_OpportunityEvaluation_TEST {
 
     /***
     * @description Verifies the batch job creates an Opp with correct CloseDate when
-    * DayOfMonth=31 (converted to Last_Day), StartDate is in February, and the batch
-    * runs on day 31 of a subsequent month. The next donation date should not skip a month.
+    * DayOfMonth=30, StartDate is in February, and the batch runs before the donation
+    * date in a subsequent month. The next donation date should not skip a month.
     * Regression test for W-19306508.
     */
     @IsTest
-    private static void shouldNotSkipMonthForNextOppWhenBatchRunsOnDay31WithFebStart() {
+    private static void shouldNotSkipMonthForNextOppWhenBatchRunsBeforeDayOfMonthWithFebStart() {
         RD2_EnablementService_TEST.setRecurringDonations2Enabled();
 
         final Date startDate = Date.newInstance(2021, 2, 1);
@@ -1370,7 +1370,7 @@ public with sharing class RD2_OpportunityEvaluation_TEST {
 
         npe03__Recurring_Donation__c rd = getRecurringDonationBuilder()
             .withStartDate(startDate)
-            .withDayOfMonth('31')
+            .withDayOfMonth('30')
             .withCalculateNextDonationDate()
             .build();
         insert rd;
@@ -1378,9 +1378,10 @@ public with sharing class RD2_OpportunityEvaluation_TEST {
         List<Opportunity> opps = oppGateway.getRecords(rd);
         System.assertEquals(1, opps.size(), 'An Opp should be created on insert');
         System.assertEquals(Date.newInstance(2021, 2, 28), opps[0].CloseDate,
-            'First Opp CloseDate should be Feb 28 (last day of Feb)');
+            'First Opp CloseDate should be Feb 28 (day 30 clamped to end of Feb)');
 
-        final Date batchRunDate = Date.newInstance(2021, 7, 31);
+        final Date batchRunDate = Date.newInstance(2021, 7, 29);
+        final Date expectedCloseDate = Date.newInstance(2021, 7, 30);
         RD2_ScheduleService.currentDate = batchRunDate;
 
         runBatch(new RD2_OpportunityEvaluation_BATCH(batchRunDate));
@@ -1393,10 +1394,10 @@ public with sharing class RD2_OpportunityEvaluation_TEST {
         System.assertEquals(2, opps.size(), 'A second Opp should be created by the batch');
 
         Opportunity newOpp = opps[0].CloseDate > opps[1].CloseDate ? opps[0] : opps[1];
-        System.assertEquals(batchRunDate, newOpp.CloseDate,
-            'New Opp CloseDate should be July 31, not skip to August 31');
-        System.assertEquals(batchRunDate, rd.npe03__Next_Payment_Date__c,
-            'Next Payment Date should be July 31');
+        System.assertEquals(expectedCloseDate, newOpp.CloseDate,
+            'New Opp CloseDate should be July 30, not skip to August');
+        System.assertEquals(expectedCloseDate, rd.npe03__Next_Payment_Date__c,
+            'Next Payment Date should be July 30');
     }
 
     // Helpers
diff --git a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
index 0814bcfc52f..55786430d93 100644
--- a/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
+++ b/force-app/main/default/classes/RD2_ScheduleService_TEST.cls
@@ -1755,9 +1755,9 @@ public with sharing class RD2_ScheduleService_TEST {
     }
 
     /***
-    * @description Verifies visualized installments are not skipped when DayOfMonth=31,
+    * @description Verifies visualized installments are not skipped when DayOfMonth=30,
     * StartDate is in February, and visualization starts from a late day in March.
-    * The first installment shown should be Mar 31, not skip to Apr 30.
+    * The first installment shown should be Mar 30, not skip to April.
     * Regression test for W-19306508.
     */
     @isTest
@@ -1770,7 +1770,7 @@ public with sharing class RD2_ScheduleService_TEST {
 
         npe03__Recurring_Donation__c rd = getRecurringDonationMonthlyBuilder()
             .withStartDate(startDate)
-            .withDayOfMonth('31')
+            .withDayOfMonth('30')
             .build();
 
         Test.startTest();
@@ -1784,12 +1784,12 @@ public with sharing class RD2_ScheduleService_TEST {
             viewDate, 3, schedules);
 
         System.assertEquals(3, installments.size(), 'Should return 3 installments');
-        System.assertEquals(Date.newInstance(2021, 3, 31), installments[0].nextDonationDate,
-            'First visualized installment should be March 31, not skip to April');
+        System.assertEquals(Date.newInstance(2021, 3, 30), installments[0].nextDonationDate,
+            'First visualized installment should be March 30, not skip to April');
         System.assertEquals(Date.newInstance(2021, 4, 30), installments[1].nextDonationDate,
             'Second installment should be April 30');
-        System.assertEquals(Date.newInstance(2021, 5, 31), installments[2].nextDonationDate,
-            'Third installment should be May 31');
+        System.assertEquals(Date.newInstance(2021, 5, 30), installments[2].nextDonationDate,
+            'Third installment should be May 30');
     }
 
     /***

From 7801843be8e03e4fce287affdf1561b8f3e859d7 Mon Sep 17 00:00:00 2001
From: Andrew Yu <andrew.yu@salesforce.com>
Date: Tue, 12 May 2026 09:41:43 -0700
Subject: [PATCH 7/7] Add detailed comments to getNextDonationDateGreaterThan
 documenting the 6-step algorithm

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../default/classes/RD2_ScheduleService.cls   | 36 +++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/force-app/main/default/classes/RD2_ScheduleService.cls b/force-app/main/default/classes/RD2_ScheduleService.cls
index a6bf3cb0c08..e40be1187c0 100644
--- a/force-app/main/default/classes/RD2_ScheduleService.cls
+++ b/force-app/main/default/classes/RD2_ScheduleService.cls
@@ -524,29 +524,57 @@ public without sharing class RD2_ScheduleService {
     }
 
     /***
-    * @description Calculates the next donation date >= referenced date
+    * @description Calculates the next donation date that is on or after the given reference date.
+    *
+    * Algorithm:
+    * 1. Compute the first valid donation date from the schedule's start date (honoring DayOfMonth).
+    * 2. If that date already meets or exceeds the reference date, return it immediately.
+    * 3. Otherwise, use arithmetic to fast-forward close to the reference date in one step:
+    *    compute how many period-units (months/days/years) lie between the first valid date and
+    *    the reference date, then jump forward by the largest multiple of the installment frequency
+    *    that fits (integer division, so the result is <= referenceDate).
+    * 4. For monthly schedules, snap the result to the correct DayOfMonth (handles short months
+    *    and "Last_Day").
+    * 5. If the jump landed before the reference date (due to integer division truncation),
+    *    advance by one more installment period and re-snap for monthly.
+    * 6. For yearly schedules that started on the last day of a short month (e.g. Feb 29),
+    *    ensure the result also lands on the last day of its month.
+    *
     * @param schedule Recurring Donation Schedule record
     * @param referenceDate Reference date used to calculate next donation date. It can be today or a future projected date.
-    * @return Date The Next Donation Date
+    * @return Date The Next Donation Date on or after referenceDate
     */
     public Date getNextDonationDateGreaterThan(RecurringDonationSchedule__c schedule, Date referenceDate) {
+        // Step 1: Determine the earliest possible donation date from the schedule start
         Date firstValid = getFirstPossibleDonationDateFromStart(schedule);
 
+        // Step 2: If the first valid date already satisfies >= referenceDate, no calculation needed
         if (firstValid >= referenceDate) {
             return firstValid;
         }
 
+        // Step 3: Fast-forward using arithmetic instead of iterating period by period.
+        // For weekly schedules, frequency is measured in days (e.g. every 2 weeks = 14 days).
+        // For monthly/yearly, frequency is in those native units (e.g. every 3 months = 3).
         Integer adjustedFrequency =
             (schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_WEEKLY ? DAYS_IN_WEEK : 1) * Integer.valueOf(schedule.InstallmentFrequency__c);
 
+        // Compute how many period-units (months, days, or years) separate firstValid from referenceDate
         Integer unitsBetween = getDateUnitsBetweenDates(firstValid, schedule.InstallmentPeriod__c, referenceDate);
 
+        // Jump forward by the largest whole number of installment cycles that fits.
+        // Integer division truncates, so this lands on or just before the referenceDate.
         Date adjusted = addDateUnits(firstValid, (unitsBetween / adjustedFrequency) * adjustedFrequency, schedule.InstallmentPeriod__c);
 
+        // Step 4: For monthly schedules, addMonths may land on the wrong day of month
+        // (e.g. Jan 31 + 1 month = Feb 28, but DayOfMonth is "31" aka last day).
+        // Snap to the correct target day within the landed month.
         if (schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_MONTHLY && schedule.DayOfMonth__c != null) {
             adjusted = adjustToTargetDayOfMonth(adjusted, schedule);
         }
 
+        // Step 5: If integer division truncation caused us to land before the referenceDate,
+        // advance exactly one more installment period and re-snap for monthly.
         if (adjusted < referenceDate) {
             adjusted = addDateUnits(adjusted, adjustedFrequency, schedule.InstallmentPeriod__c);
 
@@ -555,6 +583,10 @@ public without sharing class RD2_ScheduleService {
             }
         }
 
+        // Step 6: Yearly edge case — if the schedule started on the last day of a short month
+        // (e.g. Feb 29 in a leap year), addYears may land on a different day (Feb 28).
+        // Detect this by checking if the start day equals the last day of the adjusted month,
+        // and if so, correct to the actual last day of the target month.
         if (
             schedule.InstallmentPeriod__c == RD2_Constants.INSTALLMENT_PERIOD_YEARLY &&
             schedule.StartDate__c.day() != adjusted.day() &&