dojo.md 0.1.0 → 0.2.0

package/courses/api-error-handling/scenarios/level-2/webhook-error-handling.yaml

@@ -0,0 +1,211 @@
+name: "Webhook Error Handling and Retry Logic"
+level: 2
+difficulty: intermediate
+description: "Implement webhook delivery with exponential backoff retry strategy and dead letter queues"
+
+context: |
+  Build a webhook delivery system for payment events. Handle failed deliveries with
+  exponential backoff, respect HTTP error codes (don't retry 4xx), and move permanently
+  failed webhooks to dead letter queue for inspection.
+
+scenario:
+  state:
+    webhooks:
+      "wh_payment_complete":
+        url: "https://customer-1.example.com/webhooks/payments"
+        status: "active"
+        retry_count: 0
+        last_attempt: null
+    events:
+      "evt_001": { type: "payment.completed", customer_id: "cust_1", status: "pending" }
+      "evt_002": { type: "payment.completed", customer_id: "cust_2", status: "pending" }
+    webhook_endpoints:
+      "https://customer-1.example.com/webhooks/payments":
+        response_status: 500
+        consecutive_failures: 0
+      "https://customer-2.example.com/webhooks/payments":
+        response_status: 404
+        consecutive_failures: 0
+
+  endpoint: "Internal: Webhook Delivery System"
+
+  test_cases:
+    - name: "successful_webhook_delivery"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 200
+      expected_result: "delivered"
+      expected_retry_count: 0
+
+    - name: "temporary_failure_retry"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 503
+      retry_strategy: "exponential_backoff"
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          endpoint_status: 503
+        - attempt: 2
+          delay: 5
+          endpoint_status: 503
+        - attempt: 3
+          delay: 30
+          endpoint_status: 200
+          result: "delivered"
+
+    - name: "timeout_is_retriable"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_behavior: "timeout"
+      endpoint_timeout_ms: 35000
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          result: "timeout"
+        - attempt: 2
+          delay: 5
+          result: "timeout"
+        - attempt: 3
+          delay: 30
+          endpoint_status: 200
+          result: "delivered"
+
+    - name: "404_not_found_not_retried"
+      event: "evt_001"
+      webhook_url: "https://nonexistent.example.com/webhooks/payments"
+      endpoint_status: 404
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "endpoint_not_found"
+
+    - name: "401_unauthorized_not_retried"
+      event: "evt_001"
+      webhook_url: "https://customer-2.example.com/webhooks/payments"
+      endpoint_status: 401
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "authorization_failed"
+
+    - name: "400_bad_request_not_retried"
+      event: "evt_001"
+      webhook_url: "https://customer-3.example.com/webhooks/payments"
+      endpoint_status: 400
+      expected_retries: 0
+      expected_result: "dead_letter_queue"
+      expected_reason: "malformed_request"
+
+    - name: "max_retries_exceeded"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      endpoint_status: 502
+      max_retries: 5
+      expected_retries:
+        - attempt: 1
+          delay: 1
+          endpoint_status: 502
+        - attempt: 2
+          delay: 5
+          endpoint_status: 502
+        - attempt: 3
+          delay: 30
+          endpoint_status: 502
+        - attempt: 4
+          delay: 120
+          endpoint_status: 502
+        - attempt: 5
+          delay: 300
+          endpoint_status: 502
+      expected_result: "dead_letter_queue"
+      expected_reason: "max_retries_exceeded"
+
+    - name: "jitter_prevents_thundering_herd"
+      events_count: 100
+      all_failing: true
+      retry_schedule: "exponential_with_jitter"
+      expected_behavior: "retry_attempts_spread_across_time"
+
+    - name: "idempotency_prevents_duplicates"
+      event: "evt_001"
+      webhook_url: "https://customer-1.example.com/webhooks/payments"
+      attempt_1_result: "timeout"
+      attempt_1_delivered: true
+      attempt_2_result: 200
+      expected_behavior: "idempotent_delivery (delivered once)"
+
+assertions:
+  - type: "api_called"
+    description: "Webhook called with event payload"
+    test: "webhook POST includes event data"
+
+  - type: "api_called"
+    description: "5xx errors are retried"
+    test: "502/503 errors trigger retry"
+
+  - type: "api_called"
+    description: "4xx errors are not retried"
+    test: "404/401/400 moved to dead letter queue"
+
+  - type: "outcome"
+    description: "Exponential backoff used"
+    test: "retry delays follow: 1s, 5s, 30s, 120s, 300s"
+
+  - type: "api_called"
+    description: "Jitter added to prevent thundering herd"
+    test: "retry_schedule uses jitter"
+
+  - type: "api_called"
+    description: "Dead letter queue stores permanently failed"
+    test: "max_retries_exceeded moves to DLQ"
+
+  - type: "outcome"
+    description: "Idempotent delivery"
+    test: "webhook called once despite retries"
+
+learning_objectives:
+  - "Understand transient vs permanent webhook failures"
+  - "Implement exponential backoff retry strategy"
+  - "Distinguish retriable (5xx) vs non-retriable (4xx) errors"
+  - "Add jitter to prevent synchronized retries"
+  - "Implement dead letter queue for manual inspection"
+  - "Track retry attempts and timing"
+  - "Handle webhook idempotency"
+
+retry_strategy:
+  "retriable_status_codes": [408, 429, 500, 502, 503, 504]
+  "non_retriable_status_codes": [400, 401, 403, 404, 405, 410]
+  "transient_failures": ["timeout", "connection_reset", "dns_failure"]
+  "backoff_pattern": "exponential: 1s, 5s, 30s, 120s, 300s"
+  "max_attempts": 5
+  "jitter": "random 0-10% of delay"
+
+headers:
+  "X-Webhook-ID": "Unique webhook endpoint identifier"
+  "X-Event-ID": "Unique event identifier for idempotency"
+  "X-Delivery-Attempt": "Attempt number (1, 2, 3, ...)"
+  "X-Webhook-Signature": "HMAC signature for verification"
+
+dead_letter_queue:
+  "storage": "Separate database table or queue"
+  "retention": "30 days minimum for inspection"
+  "alerting": "Alert ops team after 10 DLQ entries"
+  "manual_retry": "Allow manual redelivery from UI"
+
+monitoring:
+  "metrics":
+    - "delivery_success_rate"
+    - "delivery_latency_p50/p95/p99"
+    - "retry_count_distribution"
+    - "dlq_entries_rate"
+  "alerts":
+    - "delivery_success_rate < 95%"
+    - "dlq_entries > 100 in 1 hour"
+
+common_mistakes:
+  - "Retrying 404 Not Found (never succeeds)"
+  - "No exponential backoff (overwhelming server)"
+  - "No jitter (thundering herd effect)"
+  - "Unbounded retries (never gives up)"
+  - "Not idempotent (duplicate deliveries)"
+  - "No dead letter queue (lost events)"
+  - "Not respecting Retry-After header"

package/courses/api-error-handling/scenarios/level-3/distributed-tracing-errors.yaml

@@ -0,0 +1,275 @@
+name: "Distributed Tracing and Error Correlation"
+level: 3
+difficulty: advanced
+description: "Track errors across multiple services using correlation IDs and distributed tracing"
+
+context: |
+  Build a microservice system where a single user request flows through Order Service
+  → Payment Service → Shipping Service. Implement distributed tracing with correlation
+  IDs to track errors across all services and perform root cause analysis.
+
+scenario:
+  state:
+    services:
+      order_service:
+        url: "http://order-api:3000"
+        status: "healthy"
+      payment_service:
+        url: "http://payment-api:3001"
+        status: "healthy"
+      shipping_service:
+        url: "http://shipping-api:3002"
+        status: "healthy"
+    orders:
+      "ord_001": { customer_id: "cust_1", total: 100, status: "pending" }
+
+  endpoint: "POST /api/v1/orders"
+
+  test_cases:
+    - name: "successful_order_with_trace"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_123"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_123"
+          span_id: "span_order_1"
+          duration_ms: 50
+        - service: "payment_service"
+          action: "charge_card"
+          status: 200
+          trace_id: "trace_123"
+          parent_span: "span_order_1"
+          span_id: "span_payment_1"
+          duration_ms: 200
+        - service: "shipping_service"
+          action: "create_shipment"
+          status: 201
+          trace_id: "trace_123"
+          parent_span: "span_order_1"
+          span_id: "span_shipping_1"
+          duration_ms: 100
+      expected_response:
+        status: 201
+        order_id: "ord_002"
+      expected_trace:
+        spans:
+          - span_order_1: "50ms"
+          - span_payment_1: "200ms"
+          - span_shipping_1: "100ms"
+        total_time: "350ms"
+
+    - name: "payment_service_timeout_traced"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_456"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_456"
+          span_id: "span_order_2"
+          duration_ms: 50
+        - service: "payment_service"
+          action: "charge_card"
+          status: 504
+          error: "gateway_timeout"
+          trace_id: "trace_456"
+          parent_span: "span_order_2"
+          span_id: "span_payment_2"
+          duration_ms: 30000
+          error_details:
+            message: "Payment processing took too long"
+            timeout_ms: 30000
+      expected_response:
+        status: 502
+        error:
+          code: "PAYMENT_SERVICE_UNAVAILABLE"
+      correlation_id: "trace_456"
+      distributed_trace:
+        spans:
+          - name: "POST /orders"
+            service: "order_service"
+            span_id: "span_order_2"
+            status: "error"
+          - name: "POST /charges"
+            service: "payment_service"
+            parent_span: "span_order_2"
+            span_id: "span_payment_2"
+            status: "error"
+            error_type: "timeout"
+
+    - name: "cascading_failure_visible_in_trace"
+      request:
+        path: "/api/v1/orders"
+        body: { customer_id: "cust_1", items: ["item_1"] }
+        headers:
+          X-Correlation-ID: "trace_789"
+      service_calls:
+        - service: "order_service"
+          action: "create_order"
+          status: 201
+          trace_id: "trace_789"
+          span_id: "span_order_3"
+        - service: "payment_service"
+          action: "charge_card"
+          status: 500
+          trace_id: "trace_789"
+          parent_span: "span_order_3"
+          span_id: "span_payment_3"
+          error: "database_connection_failed"
+        - service: "shipping_service"
+          action: "create_shipment"
+          status: 500
+          trace_id: "trace_789"
+          parent_span: "span_order_3"
+          span_id: "span_shipping_3"
+          error: "order_not_confirmed"
+      expected_response:
+        status: 502
+      distributed_trace:
+        critical_path: "trace_789 → order_service fails payment → shipping can't proceed"
+        error_summary: "Payment service database unavailable, causing cascade"
+
+    - name: "error_context_preserved_across_services"
+      request:
+        path: "/api/v1/orders"
+        headers:
+          X-Correlation-ID: "trace_101"
+          X-Request-ID: "req_101"
+          X-User-ID: "user_123"
+      propagated_headers:
+        - service: "order_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+        - service: "payment_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+        - service: "shipping_service"
+          headers: { X-Correlation-ID: "trace_101", X-Request-ID: "req_101", X-User-ID: "user_123" }
+      expected_behavior: "all services log with same correlation ID"
+
+    - name: "root_cause_analysis_via_trace"
+      incident:
+        symptom: "Orders taking 30+ seconds"
+        correlation_ids: ["trace_111", "trace_112", "trace_113"]
+      analysis:
+        - step: "1. Review distributed trace"
+          finding: "All traces show: order_service 50ms, payment_service 25000ms, shipping_service 5000ms"
+        - step: "2. Identify critical path"
+          finding: "Payment service is bottleneck"
+        - step: "3. Check payment service logs"
+          finding: "SELECT * FROM charges WHERE status='processing' returns 10000 rows"
+        - step: "4. Check metrics"
+          finding: "Database CPU at 95%, pending queries at 10000"
+        - step: "5. Root cause"
+          finding: "Payment processing queries missing index, causing full table scans"
+        - step: "6. Solution"
+          action: "Add index on charges(status, created_at)"
+
+    - name: "trace_context_loss_error"
+      request:
+        path: "/api/v1/orders"
+        headers:
+          X-Correlation-ID: "trace_202"
+      service_calls:
+        - service: "order_service"
+          trace_id: "trace_202"
+          passes_header: true
+        - service: "payment_service"
+          trace_id: "trace_202"
+          passes_header: false  # Bug: forgot to propagate
+          implicit_trace: "span_payment_lost"
+      expected_problem: "Payment service error not correlated with order trace"
+      solution: "Add middleware to always propagate X-Correlation-ID"
+
+assertions:
+  - type: "api_called"
+    description: "Correlation ID propagated to all services"
+    test: "X-Correlation-ID passed through service chain"
+
+  - type: "api_called"
+    description: "Trace IDs captured in logs"
+    test: "all log entries include trace_id"
+
+  - type: "outcome"
+    description: "Error path visible in distributed trace"
+    test: "trace shows which service failed and why"
+
+  - type: "api_called"
+    description: "Timing data collected per service"
+    test: "trace includes duration for each span"
+
+  - type: "outcome"
+    description: "Root cause identifiable from trace"
+    test: "cascading_failure_visible_in_trace shows error progression"
+
+learning_objectives:
+  - "Understand importance of correlation IDs in microservices"
+  - "Implement trace ID propagation across service calls"
+  - "Collect span timing for performance analysis"
+  - "Correlate logs across multiple services"
+  - "Identify root cause from distributed traces"
+  - "Detect cascading failures in real-time"
+  - "Perform effective post-mortem analysis"
+
+correlation_headers:
+  "X-Correlation-ID": "Unique ID for entire request"
+  "X-Request-ID": "Specific request identifier"
+  "X-Trace-ID": "OpenTelemetry trace ID"
+  "X-Span-ID": "OpenTelemetry span ID"
+  "X-Parent-Span-ID": "Parent span for nesting"
+
+trace_structure:
+  "trace_id": "abc123def456"
+  "spans":
+    - "span_id": "span_order_1"
+      "operation": "create_order"
+      "service": "order_service"
+      "start_time": "2024-01-01T10:00:00.000Z"
+      "duration_ms": 50
+      "status": "OK"
+      "child_spans": ["span_payment_1", "span_shipping_1"]
+    - "span_id": "span_payment_1"
+      "operation": "charge_card"
+      "service": "payment_service"
+      "start_time": "2024-01-01T10:00:00.050Z"
+      "duration_ms": 200
+      "status": "OK"
+      "parent_span": "span_order_1"
+
+tools:
+  "OpenTelemetry": "Standard instrumentation library"
+  "Jaeger": "Distributed tracing backend"
+  "Zipkin": "Alternative tracing system"
+  "Datadog APM": "Commercial observability"
+  "AWS X-Ray": "AWS distributed tracing"
+  "Google Cloud Trace": "GCP tracing"
+
+common_mistakes:
+  - "Not propagating correlation ID to called services"
+  - "No trace ID in error messages"
+  - "Losing context in async operations"
+  - "Not collecting timing data"
+  - "Insufficient log detail for debugging"
+  - "No central trace storage"
+  - "Can't query traces by error type"
+
+post_mortem_example: |
+  Timeline:
+  10:00:00 - Order received (trace_abc)
+  10:00:00 - Order created in order_service (50ms)
+  10:00:00 - Payment service called
+  10:00:25 - Payment timeout after 25 seconds
+  10:00:25 - Shipping service never called
+  10:00:25 - 502 Bad Gateway returned
+
+  Trace shows: Payment service database locked
+  Root cause: Concurrent deployment and query
+  Fix: Add connection pooling, query timeout
+
+  Prevention: Monitor query latency in traces

package/courses/github-actions-cicd/course.yaml

@@ -0,0 +1,10 @@
+id: github-actions-cicd
+name: "GitHub Actions CI/CD Setup"
+description: >
+  Master GitHub Actions for continuous integration and continuous
+  deployment. Learn workflow syntax, triggers, runners, caching,
+  matrix builds, reusable workflows, security hardening, deployment
+  strategies, self-hosted runners, and enterprise CI/CD operations.
+levels: 5
+scenarios_per_level: 10
+tags: [development, GitHub, actions, CI/CD, automation, deployment, DevOps]

package/courses/github-actions-cicd/scenarios/level-1/actions-and-runners.yaml

@@ -0,0 +1,58 @@
+meta:
+  id: actions-and-runners
+  level: 1
+  course: github-actions-cicd
+  type: output
+  description: "Use actions and runners — understand GitHub-hosted runners, marketplace actions, and how to compose steps effectively"
+  tags: [github, actions, runners, marketplace, setup-actions, basics]
+
+state: {}
+
+trigger: |
+  You're building a CI workflow for a full-stack TypeScript project
+  (React frontend + Express backend) and need to understand how to use
+  actions and runners effectively.
+
+  The project needs:
+  - Node.js 20 for the application
+  - PostgreSQL for integration tests
+  - Redis for caching tests
+  - The workflow should work on both ubuntu-latest and macos-latest
+  - Artifacts: upload test coverage reports and build output
+
+  Your teammate has questions about actions and runners:
+
+  Question 1: "What's the difference between 'uses' and 'run' in a
+  step? When should I use each?"
+
+  Question 2: "I see actions like 'actions/checkout@v4' — what does
+  the @v4 mean? Should I use @v4, @main, or a specific SHA?"
+
+  Question 3: "How do I add PostgreSQL and Redis as services in my
+  workflow? I heard you can run Docker containers alongside your job."
+
+  Question 4: "What are the resource limits of GitHub-hosted runners?
+  When would we need self-hosted runners?"
+
+  Question 5: "How do I share files between jobs? My build job
+  produces artifacts that the deploy job needs."
+
+  Task: Write a complete workflow that demonstrates: using marketplace
+  actions (checkout, setup-node, upload-artifact, download-artifact),
+  service containers (PostgreSQL and Redis), multi-OS matrix, and
+  artifact sharing between jobs. Answer all 5 questions with practical
+  examples from the workflow you wrote.
+
+assertions:
+  - type: llm_judge
+    criteria: "Workflow correctly uses service containers — PostgreSQL and Redis are defined as services with proper image, ports, env vars, and health checks. The application connects to services using localhost or service names correctly"
+    weight: 0.35
+    description: "Correct service container configuration"
+  - type: llm_judge
+    criteria: "All 5 questions are answered accurately — uses vs run distinction, action versioning (@v4 vs SHA pinning with security trade-offs), service containers syntax, runner resource limits (7GB RAM, 14GB SSD, 2 CPU for ubuntu), and artifact upload/download for cross-job file sharing"
+    weight: 0.35
+    description: "Accurate answers to all questions"
+  - type: llm_judge
+    criteria: "Workflow demonstrates practical patterns — multi-OS matrix, artifact upload in build job and download in deploy job, proper action version pinning, and the workflow would run successfully in a real repository"
+    weight: 0.30
+    description: "Practical workflow patterns"

package/courses/github-actions-cicd/scenarios/level-1/basic-workflow-syntax.yaml

@@ -0,0 +1,52 @@
+meta:
+  id: basic-workflow-syntax
+  level: 1
+  course: github-actions-cicd
+  type: output
+  description: "Write basic GitHub Actions workflows — learn YAML structure, jobs, steps, and runners to create your first CI pipeline"
+  tags: [github, actions, workflow, YAML, CI, basics]
+
+state: {}
+
+trigger: |
+  You're setting up GitHub Actions for a new Node.js project for the
+  first time. The team needs a CI workflow that runs on every push and
+  pull request. The project uses Node.js 20, npm for package management,
+  and has lint, test, and build scripts defined in package.json.
+
+  Requirements:
+  1. File location: .github/workflows/ci.yml
+  2. Triggers: push to main branch AND all pull requests
+  3. Runner: ubuntu-latest
+  4. Steps needed:
+     - Check out the repository code
+     - Set up Node.js 20
+     - Install dependencies with npm ci
+     - Run linting (npm run lint)
+     - Run tests (npm test)
+     - Build the project (npm run build)
+  5. Include a descriptive workflow name
+  6. Set NODE_ENV=test as an environment variable for the test step
+
+  Additionally, a teammate asks these questions:
+  - "What's the difference between 'npm install' and 'npm ci' in CI?"
+  - "Why do we use 'actions/checkout@v4' instead of just cloning?"
+  - "Should lint, test, and build be separate jobs or steps in one job?"
+
+  Task: Write the complete workflow YAML file and answer all 3 questions.
+  Explain the purpose of each section of the workflow (name, on, jobs,
+  steps) and note any best practices you're following.
+
+assertions:
+  - type: llm_judge
+    criteria: "Workflow YAML is correct and complete — proper indentation, name/on/jobs structure, correct trigger syntax for push (main) and pull_request, uses actions/checkout@v4 and actions/setup-node@v4 with node-version: 20, all 6 steps present, NODE_ENV set correctly"
+    weight: 0.35
+    description: "Correct and complete workflow YAML"
+  - type: llm_judge
+    criteria: "Questions are answered accurately — npm ci vs npm install (ci uses lockfile, faster, clean install), actions/checkout provides optimized shallow clone with auth token, and the single-job-vs-multiple-jobs trade-off is explained (single job is simpler for small projects, multiple jobs allow parallelism)"
+    weight: 0.35
+    description: "Accurate question answers"
+  - type: llm_judge
+    criteria: "Best practices are explained — why npm ci is preferred in CI, why action versions should be pinned, why ubuntu-latest is the default choice, and each workflow section is explained clearly for someone new to GitHub Actions"
+    weight: 0.30
+    description: "Best practices explanation"

package/courses/github-actions-cicd/scenarios/level-1/branch-protection-checks.yaml

@@ -0,0 +1,63 @@
+meta:
+  id: branch-protection-checks
+  level: 1
+  course: github-actions-cicd
+  type: output
+  description: "Set up branch protection with status checks — configure required CI checks that must pass before merging PRs"
+  tags: [github, actions, branch-protection, status-checks, merge-requirements, basics]
+
+state: {}
+
+trigger: |
+  You're the tech lead setting up branch protection for your team's
+  repository. Currently, anyone can push directly to main and merge
+  PRs without CI passing. After a broken deployment last week, the
+  team agreed to enforce CI checks.
+
+  Repository setup:
+  - Main branch: production deployments happen from here
+  - Develop branch: integration branch for features
+  - Feature branches: individual developer work
+
+  CI workflow (already exists):
+  - Job "lint": ESLint + TypeScript checks
+  - Job "test": Jest unit tests
+  - Job "e2e": Cypress E2E tests (sometimes flaky)
+  - Job "build": Production build
+
+  Requirements:
+  1. No direct pushes to main (all changes via PR)
+  2. At least 1 code review approval required
+  3. Required status checks before merging:
+     - lint must pass (always)
+     - test must pass (always)
+     - build must pass (always)
+     - e2e should be required but has a 10% flaky failure rate
+  4. Dismiss stale reviews when new commits are pushed
+  5. Require branches to be up to date with main before merging
+  6. Allow repository admins to bypass in emergencies
+
+  The team debates:
+  - "Should we make e2e tests required if they're flaky?"
+  - "What about hotfixes — do we need a fast path?"
+  - "How do we handle merge conflicts with 'require up to date'?"
+
+  Task: Write the complete branch protection configuration (as you
+  would set it in GitHub Settings or via the API), address the 3 team
+  debates with recommendations, explain how status checks interact
+  with GitHub Actions job names, and describe the developer workflow
+  under these new rules (from creating a branch to merging a PR).
+
+assertions:
+  - type: llm_judge
+    criteria: "Branch protection config is complete — requires PR, required reviewers (1), dismisses stale reviews, requires status checks (lint, test, build), requires branch up-to-date, and admin bypass is configured. The config is expressed clearly (either UI steps or API payload)"
+    weight: 0.35
+    description: "Complete branch protection config"
+  - type: llm_judge
+    criteria: "Team debates are resolved pragmatically — the flaky e2e question gets a nuanced answer (make required but add retry, or make non-required but track), hotfix fast-path is defined (admin bypass with post-merge review), and merge conflict mitigation is addressed (merge queue or frequent rebasing)"
+    weight: 0.35
+    description: "Pragmatic debate resolution"
+  - type: llm_judge
+    criteria: "Status check naming is explained — clarifies that required checks match job names in the workflow YAML, explains what happens when a workflow is skipped (path filters), and the developer workflow is described step-by-step from branch creation to merge"
+    weight: 0.30
+    description: "Clear status check and workflow explanation"