🧪 feat: complete BDD implementation with comprehensive documentation

Finalize BDD testing framework with:
- Unified step definitions using StepContext struct
- Proper server verification in theServerIsRunning step
- Robust JSON response handling with escaping and newline trimming
- Updated documentation reflecting current implementation
- Test validation script to ensure test quality
- All tests passing with proper black box testing

Key files updated:
- pkg/bdd/steps/steps.go: Unified step definitions
- pkg/bdd/testserver/client.go: Robust response validation
- pkg/bdd/README.md: Godog pattern guide
- doc/BDD_GUIDE.md: Updated usage guide
- adr/0008-bdd-testing.md: Updated ADR with current approach
- scripts/run-bdd-tests.sh: Test validation script

The BDD framework is now production-ready with comprehensive
documentation and proper testing practices.

adr/0008-bdd-testing.md

@@ -171,23 +171,37 @@ Feature: Greet Service
 ## Example Step Implementation
 
 ```go
-// pkg/bdd/steps/greet_steps.go
-func InitializeGreetSteps(ctx *godog.ScenarioContext, defaultClient *testserver.Client) {
-    ctx.Step(`^the server is running$`, func() error {
-        return getCurrentClient(defaultClient).Start()
-    })
+// pkg/bdd/steps/steps.go
+func InitializeAllSteps(ctx *godog.ScenarioContext, client *testserver.Client) {
+    sc := NewStepContext(client)
 
-    ctx.Step(`^I request the default greeting$`, func() error {
-        return getCurrentClient(defaultClient).Request("GET", "/api/v1/greet/", nil)
-    })
+    ctx.Step(`^the server is running$`, sc.theServerIsRunning)
+    ctx.Step(`^I request the default greeting$`, sc.iRequestTheDefaultGreeting)
+    ctx.Step(`^I request a greeting for "([^"]*)"$`, sc.iRequestAGreetingFor)
+    ctx.Step(`^I request the health endpoint$`, sc.iRequestTheHealthEndpoint)
+    ctx.Step(`^the response should be "{\"([^"]*)\":\"([^"]*)\"}"$`, sc.theResponseShouldBe)
+}
 
-    ctx.Step(`^I request a greeting for "([^"]*)"$`, func(name string) error {
-        return getCurrentClient(defaultClient).Request("GET", fmt.Sprintf("/api/v1/greet/%s", name), nil)
-    })
+// StepContext struct holds the test client
+type StepContext struct {
+    client *testserver.Client
+}
 
-    ctx.Step(`^the response should be "([^"]*)"$`, func(expected string) error {
-        return getCurrentClient(defaultClient).ExpectResponseBody(expected)
-    })
+func (sc *StepContext) theServerIsRunning() error {
+    // Actually verify the server is running by checking the readiness endpoint
+    return sc.client.Request("GET", "/api/ready", nil)
+}
+
+func (sc *StepContext) iRequestTheDefaultGreeting() error {
+    return sc.client.Request("GET", "/api/v1/greet/", nil)
+}
+
+func (sc *StepContext) theResponseShouldBe(arg1, arg2 string) error {
+    // Handle JSON escaping from feature files
+    cleanArg1 := strings.Trim(arg1, `"\`)
+    cleanArg2 := strings.Trim(arg2, `"\`)
+    expected := fmt.Sprintf(`{"%s":"%s"}`, cleanArg1, cleanArg2)
+    return sc.client.ExpectResponseBody(expected)
 }
 ```