🧪 test: implement per-scenario state isolation and enhance validate-test-suite.sh

- Add pkg/bdd/steps/scenario_state.go with thread-safe per-scenario state manager
- Update auth_steps.go, jwt_retention_steps.go to use per-scenario state accessors
- Add LastSecret and LastError fields to ScenarioState for JWT retention testing
- Update steps.go with SetScenarioKeyForAllSteps function
- Update suite.go to generate scenario keys and clear state properly
- Mark config hot-reload scenarios as @flaky (timing-sensitive)
- Fix validate-test-suite.sh: add -p 1 flag for sequential execution, filter JSON logs, add --count flag
- Add CONFIG_SCHEMA.md documenting configuration architecture
- Split greet tests into v1/v2 sub-tests with explicit v2 enable/disable

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>

pkg/bdd/testserver/server.go

@@ -124,8 +124,12 @@ func NewServer() *Server {
 func (s *Server) Start() error {
 	s.baseURL = fmt.Sprintf("http://localhost:%d", s.port)
 
+	// Determine if v2 should be enabled based on feature and tags
+	// This is the ONLY place where we check env vars for v2 configuration
+	v2Enabled := s.shouldEnableV2()
+
 	// Create real server instance from pkg/server
-	cfg := createTestConfig(s.port)
+	cfg := createTestConfig(s.port, v2Enabled)
 	realServer := server.NewServer(cfg, context.Background())
 
 	// Store auth service for cleanup
@@ -229,9 +233,24 @@ func (s *Server) ReloadConfig() error {
 		}
 	}
 
-	// Recreate server with new config
-	cfg := createTestConfig(s.port)
-	realServer := server.NewServer(cfg, context.Background())
+	// Recreate server with new config from file
+	// This is the ONLY feature that uses config file hot-reload
+	feature := os.Getenv("FEATURE")
+
+	var realServer *server.Server
+	if feature == "config" {
+		// For config feature: load config from the monitored file
+		cfg, err := s.loadConfigFromFile()
+		if err != nil {
+			log.Warn().Err(err).Msg("Failed to load config from file, using defaults")
+			cfg = createTestConfig(s.port, false)
+		}
+		realServer = server.NewServer(cfg, context.Background())
+	} else {
+		// For other features: use defaults with v2 check
+		cfg := createTestConfig(s.port, s.shouldEnableV2())
+		realServer = server.NewServer(cfg, context.Background())
+	}
 	s.httpServer = &http.Server{
 		Addr:    fmt.Sprintf(":%d", s.port),
 		Handler: realServer.Router(),
@@ -250,6 +269,54 @@ func (s *Server) ReloadConfig() error {
 	return s.waitForServerReady()
 }
 
+// loadConfigFromFile loads configuration from the monitored config file
+// Used for config feature hot-reload tests only
+func (s *Server) loadConfigFromFile() (*config.Config, error) {
+	feature := os.Getenv("FEATURE")
+	if feature == "" {
+		return nil, fmt.Errorf("FEATURE not set")
+	}
+
+	configPath := fmt.Sprintf("features/%s/%s-test-config.yaml", feature, feature)
+
+	v := viper.New()
+	v.SetConfigFile(configPath)
+	v.SetConfigType("yaml")
+
+	if err := v.ReadInConfig(); err != nil {
+		return nil, fmt.Errorf("failed to read config file %s: %w", configPath, err)
+	}
+
+	var cfg config.Config
+	if err := v.Unmarshal(&cfg); err != nil {
+		return nil, fmt.Errorf("failed to unmarshal config from %s: %w", configPath, err)
+	}
+
+	// Apply BDD test infrastructure defaults that should NOT come from config file
+	// These are specific to the test environment
+	cfg.Database.Host = getDatabaseHost()
+	cfg.Database.Port = getDatabasePort()
+	cfg.Database.User = "postgres"
+	cfg.Database.Password = "postgres"
+	cfg.Database.Name = "dance_lessons_coach"
+	cfg.Database.SSLMode = "disable"
+
+	// Ensure auth defaults
+	if cfg.Auth.JWTSecret == "" {
+		cfg.Auth.JWTSecret = "test-secret-key-for-bdd-tests"
+	}
+	if cfg.Auth.AdminMasterPassword == "" {
+		cfg.Auth.AdminMasterPassword = "admin123"
+	}
+
+	// Ensure logging default
+	if cfg.Logging.Level == "" {
+		cfg.Logging.Level = "debug"
+	}
+
+	return &cfg, nil
+}
+
 // initDBConnection initializes a direct database connection for cleanup operations
 func (s *Server) initDBConnection() error {
 	// Get feature-specific configuration
@@ -260,29 +327,18 @@ func (s *Server) initDBConnection() error {
 		// Try to load feature-specific config
 		configPath := fmt.Sprintf("features/%s/%s-test-config.yaml", feature, feature)
 		if _, err := os.Stat(configPath); err == nil {
-			v := viper.New()
-			v.SetConfigFile(configPath)
-			v.SetConfigType("yaml")
-
-			if readErr := v.ReadInConfig(); readErr == nil {
-				var featureCfg config.Config
-				if unmarshalErr := v.Unmarshal(&featureCfg); unmarshalErr == nil {
-					// Set default values if not configured
-					if featureCfg.Auth.JWTSecret == "" {
-						featureCfg.Auth.JWTSecret = "default-secret-key-please-change-in-production"
-					}
-					if featureCfg.Auth.AdminMasterPassword == "" {
-						featureCfg.Auth.AdminMasterPassword = "admin123"
-					}
-					cfg = &featureCfg
-				}
+			var loadErr error
+			cfg, loadErr = s.loadConfigFromFile()
+			if loadErr != nil {
+				log.Warn().Err(loadErr).Str("path", configPath).Msg("Failed to load config, using defaults")
+				cfg = nil
 			}
 		}
 	}
 
 	// Fallback to default config if feature-specific not available
 	if cfg == nil {
-		cfg = createTestConfig(s.port)
+		cfg = createTestConfig(s.port, s.shouldEnableV2())
 	}
 
 	dsn := fmt.Sprintf(
@@ -582,8 +638,26 @@ func (s *Server) waitForServerReady() error {
 	}
 }
 
+// shouldEnableV2 determines if v2 API should be enabled for this test server
+// This is the ONLY place that reads FEATURE and GODOG_TAGS env vars
+func (s *Server) shouldEnableV2() bool {
+	feature := os.Getenv("FEATURE")
+
+	// Only check for v2 in greet feature (where we have @v2 tagged scenarios)
+	if feature != "greet" {
+		// For config feature, v2 is controlled via config file hot-reload
+		// For other features, v2 is disabled by default
+		return false
+	}
+
+	// For greet feature: enable v2 if tags include @v2
+	tags := os.Getenv("GODOG_TAGS")
+	return strings.Contains(tags, "@v2")
+}
+
 // createTestConfig creates a test configuration
-func createTestConfig(port int) *config.Config {
+// Pass v2Enabled explicitly to avoid reading env vars deep in the stack
+func createTestConfig(port int, v2Enabled bool) *config.Config {
 	return &config.Config{
 		Server: config.ServerConfig{
 			Host: "0.0.0.0",
@@ -604,6 +678,9 @@ func createTestConfig(port int) *config.Config {
 				TTL: 24 * time.Hour,
 			},
 		},
+		API: config.APIConfig{
+			V2Enabled: v2Enabled,
+		},
 		Logging: config.LoggingConfig{
 			Level: "debug",
 		},