Prevent Phase 4 from using wrong service (ngit-relay vs ngit-grasp)

Add validation to ensure Phase 4 scripts use ngit-grasp service
(with structured logging) instead of ngit-relay service.

Changes:
- Add validate-service.sh helper for reusable service validation
- Add validation to run-migration-analysis.sh before Phase 4
- Add validation to 30-extract-parse-failures.sh
- Add validation to 31-extract-purgatory-expiry.sh
- Update migration guide with clear warnings about service selection
- Expand troubleshooting for 'Phase 4 finds no logs' issue
- Emphasize lesson learned in relay.ngit.dev notes

This prevents the issue where Phase 4 was run against ngit-relay.service
and found no parse failures because structured logging only exists in
ngit-grasp services.

1 files changed, 28 insertions, 0 deletions

diff --git a/docs/how-to/migration-scripts/run-migration-analysis.sh b/docs/how-to/migration-scripts/run-migration-analysis.sh
index 65d9d17..b2ca142 100755
--- a/docs/how-to/migration-scripts/run-migration-analysis.sh
+++ b/docs/how-to/migration-scripts/run-migration-analysis.sh
@@ -548,6 +548,34 @@ run_phase_4() {
         return 0
     fi
     
+    # Validate service name before running Phase 4
+    # Structured logging only exists in ngit-grasp, not ngit-relay
+    if [[ "$SERVICE_NAME" == *"ngit-relay"* ]]; then
+        log_error "SERVICE_NAME appears to be ngit-relay: $SERVICE_NAME"
+        log_error ""
+        log_error "Phase 4 requires an ngit-grasp service with structured logging."
+        log_error "Structured logging ([PARSE_FAIL], [PURGATORY_EXPIRED]) only exists"
+        log_error "in ngit-grasp services, NOT in ngit-relay services."
+        log_error ""
+        log_error "Please update --service to use the ngit-grasp archive service."
+        log_error ""
+        log_error "To find the correct service name:"
+        log_error "  systemctl list-units 'ngit-grasp*' --all"
+        log_error ""
+        log_error "Common ngit-grasp service names:"
+        log_error "  - ngit-grasp.service"
+        log_error "  - ngit-grasp-relay-ngit-dev.service (NixOS multi-instance)"
+        log_error "  - ngit-grasp-archive.service"
+        return 1
+    fi
+    
+    # Warn if service name doesn't look like ngit-grasp
+    if [[ "$SERVICE_NAME" != *"ngit-grasp"* && "$SERVICE_NAME" != *"grasp"* ]]; then
+        log_warn "SERVICE_NAME doesn't contain 'ngit-grasp': $SERVICE_NAME"
+        log_warn "Structured logging only exists in ngit-grasp services."
+        log_warn "If this is not an ngit-grasp service, Phase 4 will find no logs."
+    fi
+    
     local cmds=()
     
     cmds+=("'$SCRIPT_DIR/30-extract-parse-failures.sh' '$SERVICE_NAME' '$OUTPUT_DIR/logs'")