Add MILESTONE_GATE_SKIPPED to reason_code catalog

__tests__/reason-codes.test.ts

@@ -86,7 +86,7 @@ describe('reason-codes.json catalog integrity', () => {
     }
   });
 
-  it('catalog contains the 9 known v1 codes', () => {
+  it('catalog contains the 10 known v1 codes', () => {
     const catalogCodes = new Set(catalog.codes.map((e) => e.code));
     const expectedV1Codes = [
       'SUCCESS',
@@ -98,6 +98,7 @@ describe('reason-codes.json catalog integrity', () => {
       'HORIZON_TIMEOUT',
       'HORIZON_ERROR',
       'TLS_ERROR',
+      'MILESTONE_GATE_SKIPPED',
     ];
     for (const code of expectedV1Codes) {
       expect(catalogCodes.has(code)).toBe(true);
@@ -132,6 +133,7 @@ const KNOWN_REASON_CODES = [
   'HORIZON_TIMEOUT',
   'HORIZON_ERROR',
   'TLS_ERROR',
+  'MILESTONE_GATE_SKIPPED',
 ] as const;
 
 describe('CI lock: all known reason_codes are in the catalog', () => {

docs/USAGE.md

@@ -2321,6 +2321,7 @@ The `reason_code` output is a machine-readable string that identifies why a vali
 | `HORIZON_ERROR` | ❌ `false` | ❌ | ❌ | ❌ | Horizon returned a non-404, non-timeout error (429, 502, 503, 504, etc.). |
 | `TLS_ERROR` | ❌ `false` | ❌ | ❌ | ❌ | TLS/certificate verification failed for the Horizon endpoint. Most common with private/enterprise mirrors. |
 | `FAILED` | ❌ `false` | ✅ | ✅ | ✅ | Generic fallback: the account passed the core checks but another check (e.g. minimum asset balance) caused failure. |
+| `MILESTONE_GATE_SKIPPED` | ❌ `false` | ❌ | ❌ | ❌ | Milestone gate skipped validation because the issue's milestone was not in the allowlist. No account checks were performed. |
 
 ### Switching on reason_code in downstream jobs
 
@@ -2341,6 +2342,7 @@ The `reason_code` output is a machine-readable string that identifies why a vali
       ACCOUNT_NOT_FUNDED)  echo "Contributor has not funded their account yet" ;;
       HORIZON_TIMEOUT|HORIZON_ERROR) echo "Horizon unavailable — retry later" ;;
       TLS_ERROR)           echo "Horizon TLS issue — check the endpoint certificate" ;;
+      MILESTONE_GATE_SKIPPED) echo "Milestone gate skipped — issue milestone not in allowlist" ;;
       *)                   echo "Unknown code: ${{ steps.tb.outputs.reason_code }}" ;;
     esac
 ```

schemas/reason-codes.json

@@ -94,6 +94,16 @@
       "valid": false,
       "emittedBy": "src/checks.ts (runValidationChecks fallback when no specific code applies)",
       "since": "v1"
+    },
+    {
+      "code": "MILESTONE_GATE_SKIPPED",
+      "description": "The milestone gate skipped validation because the issue's milestone was not in the allowlist. No account checks were performed.",
+      "accountFunded": false,
+      "trustlineExists": false,
+      "xlmReserveMet": false,
+      "valid": false,
+      "emittedBy": "src/index.ts (milestone gate logic)",
+      "since": "v1"
     }
   ]
 }