fix(lighthouse): allow warning-level npm audit results during test dependency setup

Updated lighthouse.sh so setup_lighthouse_environment now:
Blocks on critical/real install failures.
Allows non-critical security warnings (exit code 1) only if required packages are actually installed (lighthouse, puppeteer).
Logs explicit warning-mode continuation text.

Author: warrenchristian1telus

.docs/dev-vs-prod-inventory-and-platform-options.md

@@ -53,6 +53,14 @@ Business value:
 - Better auditability for approvals and compliance
 - Less dependence on manual security reviews
 
+Current workflow behavior snapshot:
+- A fail-fast Lighthouse dependency preflight gate runs in `checkEnv` for `dev`, `test`, and `prod` on PR/push/schedule/manual runs.
+- The gate attempts automatic lockfile-only remediation, then re-audits before deciding pass/fail.
+- The deployment pipeline proceeds only when high/critical Lighthouse dependency issues are resolved or remediated.
+- This reduces late-stage failures and prevents deploying with known vulnerable test-tool dependency states.
+- Deploy concurrency is guarded with cancel-in-progress to prevent overlapping release races on the same ref.
+- Health-check and cluster monitoring controls are part of the deployment path to improve resilience during rollout.
+
 ### 3) Dependency and Version Governance
 
 What it means:
@@ -200,4 +208,5 @@ Examples from dev not in prod include:
 
 - `.github/workflows/build.yml` and related workflows
   - Significant preflight/security/guardrail expansion
+  - Branch-aware fail-fast dependency preflight with remediation and re-validation
 

.docs/diagrams/build-deployment-flow.md

@@ -3,7 +3,7 @@
 ## Complete CI/CD Pipeline Architecture
 
 ```mermaid
-flowchart TD
+graph TD
     Start([🎯 GitHub Push/Schedule]) --> Trigger{Event Type?}
 
     Trigger -->|Push to Branch| Branch[📌 Branch Detection<br/>950003-dev/test/prod]
@@ -86,7 +86,7 @@ flowchart TD
 
     Database --> Cache[💾 Cache Layer<br/>- Redis Sentinel<br/>- 3 replicas<br/>- Failover support<br/>- Proxy tunneling]
 
-    Cache --> App[🎓 Application Layer<br/>- Moodle pods<br/>- PHP-FPM processing<br/>- Session handling<br/>- File storage (PVC)]
+    Cache --> App[🎓 Application Layer<br/>- Moodle pods<br/>- PHP-FPM processing<br/>- Session handling<br/>- PVC file storage]
 
     App --> WebTier[🌐 Web Tier<br/>- Nginx pods<br/>- SSL termination<br/>- Load balancing<br/>- Static content]
 
@@ -112,7 +112,7 @@ flowchart TD
 
     DeploySuccess --> PostDeploy[📊 POST-DEPLOYMENT PHASE]
 
-    PostDeploy --> NPMAudit[🔒 NPM Security Audit<br/>~30 seconds<br/>**BEFORE** Lighthouse<br/>Supply chain protection]
+    PostDeploy --> NPMAudit[🔒 NPM Security Audit<br/>~30 seconds<br/>Before Lighthouse<br/>Supply chain protection]
 
     NPMAudit --> NPMResult{NPM Vulns?}
 
@@ -167,13 +167,13 @@ flowchart TD
 ## Environment-Specific Configuration
 
 ```mermaid
-flowchart LR
+graph LR
     subgraph "🟢 Development (950003-dev)"
         DevConfig["🔧 Configuration<br/>────────────<br/>Security: BASIC + WARN<br/>Scan Time: ~2-3 min<br/>Containers: NO<br/>────────────<br/>Builds: Usually SKIP<br/>Deploy: Fast iteration<br/>Migration: Auto<br/>────────────<br/>Monitoring: Basic"]
 
         DevFlow["📊 Flow<br/>────────────<br/>1. Quick security check<br/>2. Use cached images<br/>3. Deploy immediately<br/>4. Light testing<br/>────────────<br/>Total: ~5-10 min"]
 
-        DevResult["✅ Result<br/>────────────<br/>Speed: ⚡ FAST<br/>Security: ⚠️ WARN only<br/>Testing: 🔍 Minimal<br/>────────────<br/>Best for rapid dev"]
+        DevResult["✅ Result<br/>────────────<br/>Speed: ⚡ FAST<br/>Security: ⚠️ Core scan warn-only<br/>Preflight: may fail unresolved High/Critical<br/>────────────<br/>Best for rapid dev"]
     end
 
     subgraph "🟡 Test (950003-test)"
@@ -253,7 +253,7 @@ gantt
 ## Image Build Architecture
 
 ```mermaid
-flowchart TD
+graph TD
     subgraph "Base Images (External)"
         PHPBase[🐘 php:8.1-fpm<br/>Official PHP]
         NginxBase[🌐 nginx:1.25-alpine<br/>Official Nginx]
@@ -305,7 +305,7 @@ flowchart TD
 ## Security Integration Points
 
 ```mermaid
-flowchart TD
+graph TD
     Start([CI/CD Pipeline Start]) --> P1[🔒 Phase 1: Pre-Build Security<br/>~2-8 min]
 
     P1 --> S1[📋 Security Config Check]

.docs/diagrams/security-scanning-flow.md

@@ -3,7 +3,7 @@
 ## Complete Security Scanning Architecture
 
 ```mermaid
-flowchart TD
+graph TD
     Start([GitHub Action Triggered]) --> CheckEnv[🔍 checkEnv Job]
 
     CheckEnv --> Config[📋 Read Security Config<br/>SCAN_LEVEL, EXIT_ON, etc.]
@@ -98,7 +98,7 @@ flowchart TD
 ## Configuration Impact Flow
 
 ```mermaid
-flowchart LR
+graph LR
     subgraph Environment Variables
         ENABLED[SECURITY_SCAN_ENABLED]
         LEVEL[SECURITY_SCAN_LEVEL]
@@ -109,7 +109,7 @@ flowchart LR
 
     subgraph "Dev Environment"
         DevConfig["LEVEL: BASIC<br/>EXIT: WARN<br/>CONTAINERS: NO"]
-        DevResult["⚡ ~2-3 min<br/>🟢 Never Fails<br/>📊 Reports Only"]
+        DevResult["⚡ ~2-3 min<br/>🟢 Core scan warn-only<br/>⚠️ Preflight may fail unresolved High/Critical"]
     end
 
     subgraph "Test Environment"
@@ -148,7 +148,7 @@ flowchart LR
 ## Security Scanning Decision Tree
 
 ```mermaid
-flowchart TD
+graph TD
     Start([Security Scan Triggered]) --> Q1{Environment?}
 
     Q1 -->|Dev| DevPath[BASIC + WARN + NO Containers]
@@ -239,7 +239,7 @@ sequenceDiagram
 ## Vulnerability Severity Exit Strategy
 
 ```mermaid
-flowchart TD
+graph TD
     Vuln[Vulnerabilities Detected] --> Parse[Parse Severity Counts<br/>Critical, High, Medium, Low]
 
     Parse --> Strategy{EXIT_ON<br/>Strategy?}

.docs/security-scanning-best-practices.md

@@ -2,8 +2,8 @@
 
 ## 📋 Executive Summary
 
-**Current State:** Security scans run in multiple places (pre-build, post-deployment) with some redundancy
-**Recommended State:** Shift security left with fail-fast pre-build validation
+**Current State:** Shift-left controls are active in `checkEnv` with pre-build validation and branch-aware preflight dependency gating.
+**Recommended State:** Continue hardening with targeted post-build and observability improvements.
 **Benefits:**
 - ⚡ Faster feedback (don't build if supply chain is compromised)
 - 💰 Cost savings (avoid building vulnerable images)
@@ -238,11 +238,11 @@ jobs:
 ## 🛠️ Implementation Checklist
 
 ### Immediate Actions:
-- [ ] Move Trivy installation to `checkEnv` job (before builds)
-- [ ] Add pre-build security scan function call in `checkEnv`
-- [ ] Configure scan to exit with code 1 on CRITICAL
-- [ ] Add post-build image scans after each Docker build
-- [ ] Remove redundant container scans from `lighthouse-check`
+- [x] Move Trivy installation to `checkEnv` job (before builds)
+- [x] Add pre-build security scan function call in `checkEnv`
+- [x] Configure scan to enforce branch-aware fail-fast behavior
+- [ ] Add explicit post-build image scan assertions after each Docker build
+- [ ] Remove redundant container scans from `lighthouse-check` where applicable
 
 ### Future Enhancements:
 - [ ] Cache Trivy vulnerability database

.docs/security-scanning-configuration.md

@@ -27,6 +27,13 @@ SECURITY_SCAN_CONTAINERS: "NO"        # Include container scanning (expensive)
 SECURITY_SCAN_CACHE: "YES"            # Cache scan databases (faster)
 ```
 
+Additional preflight gate in `checkEnv`:
+
+- Lighthouse dependency audit runs before main scans on `pull_request`, `push`, `schedule`, and `workflow_dispatch`.
+- Target branches: `950003-dev`, `950003-test`, `950003-prod`.
+- Auto-remediation is attempted with `npm audit fix --package-lock-only --no-fund`.
+- Build fails only when high/critical vulnerabilities remain after remediation.
+
 ---
 
 ## Scan Levels
@@ -62,7 +69,7 @@ SECURITY_SCAN_LEVEL: "BASIC"       # Fast, standard checks
 SECURITY_SCAN_EXIT_ON: "WARN"      # Never block builds
 SECURITY_SCAN_CONTAINERS: "NO"     # Skip expensive scans
 ```
-**Result**: ~2-3 min, never fails, developers see warnings
+**Result**: Core security scan is warning-only (~2-3 min). Preflight can still fail on unresolved high/critical Lighthouse dependencies.
 
 ---
 

.docs/security-scanning.md

@@ -8,10 +8,20 @@ Automated security scanning runs on every build to detect vulnerabilities before
 
 | Branch | Scan Level | Blocks Build On | Duration |
 |--------|------------|-----------------|----------|
-| **950003-dev** | BASIC | Never (warnings only) | ~3 min |
+| **950003-dev** | BASIC | Core scan: warnings only. Preflight: unresolved High/Critical Lighthouse deps | ~3 min + preflight |
 | **950003-test** | FULL | High/Critical issues | ~8 min |
 | **950003-prod** | FULL | Critical issues only | ~8 min |
 
+### Preflight Gate (All Environments)
+
+Before the main security scan, `checkEnv` runs a Lighthouse dependency preflight for `950003-dev`, `950003-test`, and `950003-prod` on `pull_request`, `push`, `schedule`, and `workflow_dispatch`.
+
+- Runs `npm audit --audit-level=high --package-lock-only`
+- Attempts auto-remediation with `npm audit fix --package-lock-only --no-fund`
+- Fails the job only if high/critical issues remain after remediation
+
+This protects the pipeline from known vulnerable Lighthouse dependency states before image builds and deployment.
+
 ---
 
 ## What Gets Scanned
@@ -58,6 +68,11 @@ env:
 ### 1. Check Build Logs
 Look for `❌ CRITICAL security issues found` in the workflow output.
 
+Also check for preflight messages in `checkEnv`:
+- `Running fail-fast Lighthouse dependency audit`
+- `Attempting automatic remediation`
+- `Preflight still failing after auto-remediation`
+
 ### 2. Review Findings
 Security scan will show:
 - Package name and version