forgecraft-mcp 1.4.0 → 1.7.0

package/templates/api/mcp-servers.yaml

@@ -1,22 +1,22 @@
-tag: API
-section: mcp-servers
-servers:
-  - name: postman
-    description: "API testing and collection management via Postman workspace"
-    command: npx
-    args: ["-y", "@anthropic/mcp-server-postman"]
-    tags: [API]
-    category: testing
-    tier: recommended
-    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-postman"
-    env:
-      POSTMAN_API_KEY: ""
-
-  - name: playwright
-    description: "Browser automation for API + E2E testing, request interception, and response validation"
-    command: npx
-    args: ["-y", "@anthropic/mcp-server-playwright"]
-    tags: [API]
-    category: testing
-    tier: recommended
-    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-playwright"
+tag: API
+section: mcp-servers
+servers:
+  - name: postman
+    description: "API testing and collection management via Postman workspace"
+    command: npx
+    args: ["-y", "@anthropic/mcp-server-postman"]
+    tags: [API]
+    category: testing
+    tier: recommended
+    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-postman"
+    env:
+      POSTMAN_API_KEY: ""
+
+  - name: playwright
+    description: "Browser automation for API + E2E testing, request interception, and response validation"
+    command: npx
+    args: ["-y", "@anthropic/mcp-server-playwright"]
+    tags: [API]
+    category: testing
+    tier: recommended
+    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/mcp-server-playwright"

package/templates/api/nfr.yaml

@@ -1,23 +1,23 @@
-tag: API
-section: nfr
-blocks:
-  - id: api-performance
-    tier: recommended
-    title: "API Performance"
-    content: |
-      ## NFR: API Performance
-
-      ### Response Time Targets
-      - p50: < {{p50_target | default: 50ms}}
-      - p95: < {{p95_target | default: 200ms}}
-      - p99: < {{p99_target | default: 500ms}}
-
-      ### Throughput
-      - Target requests/sec: {{target_rps}}
-      - Load test before launch at 2x expected peak.
-      - Auto-scaling configured with appropriate min/max.
-
-      ### Rate Limiting
-      - Per-client rate limits on all endpoints.
-      - Graduated response: 429 with Retry-After header before hard block.
-      - Rate limit bypass for internal services via separate auth.
+tag: API
+section: nfr
+blocks:
+  - id: api-performance
+    tier: recommended
+    title: "API Performance"
+    content: |
+      ## NFR: API Performance
+
+      ### Response Time Targets
+      - p50: < {{p50_target | default: 50ms}}
+      - p95: < {{p95_target | default: 200ms}}
+      - p99: < {{p99_target | default: 500ms}}
+
+      ### Throughput
+      - Target requests/sec: {{target_rps}}
+      - Load test before launch at 2x expected peak.
+      - Auto-scaling configured with appropriate min/max.
+
+      ### Rate Limiting
+      - Per-client rate limits on all endpoints.
+      - Graduated response: 429 with Retry-After header before hard block.
+      - Rate limit bypass for internal services via separate auth.

package/templates/api/review.yaml

@@ -1,103 +1,103 @@
-tag: API
-section: review
-blocks:
-  - id: api-architecture-review
-    tier: recommended
-    dimension: architecture
-    title: "API Architecture Review"
-    description: |
-      Evaluate API design, endpoint structure, middleware pipeline, and service boundaries.
-    checklist:
-      - id: endpoint-design
-        description: "RESTful conventions followed: proper HTTP methods, status codes, resource naming."
-        severity: critical
-      - id: middleware-pipeline
-        description: "Middleware pipeline is ordered correctly: auth → validation → rate-limit → handler."
-        severity: important
-      - id: service-layer-separation
-        description: "Handlers are thin (validation + delegation). Business logic lives in service layer."
-        severity: critical
-      - id: api-versioning
-        description: "API versioning strategy defined and enforced (URL prefix, header, or content negotiation)."
-        severity: important
-      - id: database-migrations
-        description: "Schema changes managed through versioned migration files. Every migration is reversible. No manual DDL."
-        severity: critical
-      - id: owasp-injection
-        description: "Parameterized queries only. No string concatenation for SQL, commands, or LDAP queries."
-        severity: critical
-      - id: owasp-access-control
-        description: "Ownership checks enforced — users cannot access other users' resources. No IDOR vulnerabilities."
-        severity: critical
-      - id: security-headers
-        description: "Security headers set: CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy."
-        severity: important
-      - id: audit-logging
-        description: "Security-relevant actions logged: WHO did WHAT to WHICH resource, WHEN. Immutable, separate from app logs."
-        severity: important
-      - id: graceful-shutdown
-        description: "SIGTERM handled: stop accepting requests, drain in-flight work, close connections, exit cleanly."
-        severity: important
-      - id: container-best-practices
-        description: "Dockerfile uses multi-stage build, non-root user, pinned base image digest. Image scanned for CVEs."
-        severity: important
-      - id: health-endpoint
-        description: "/health endpoint returns status, version, uptime, and dependency connectivity. Used by orchestrator probes."
-        severity: critical
-      - id: migration-auto-deploy
-        description: "Database migrations run automatically on deploy (pre-deploy hook or init container). Never manually applied."
-        severity: important
-
-  - id: api-code-quality-review
-    tier: recommended
-    dimension: code-quality
-    title: "API Code Quality Review"
-    description: |
-      Evaluate input validation, response contracts, and error response consistency.
-    checklist:
-      - id: input-validation
-        description: "All endpoint inputs validated with schema (Zod, Joi, class-validator). No trust of client data."
-        severity: critical
-      - id: response-consistency
-        description: "All responses follow a consistent envelope: { data, error, meta }."
-        severity: important
-      - id: error-responses
-        description: "Error responses include: status code, error code, human message, request ID. No stack traces in production."
-        severity: critical
-
-  - id: api-performance-review
-    tier: recommended
-    dimension: performance
-    title: "API Performance Review"
-    description: |
-      Evaluate query efficiency, pagination, and rate limiting.
-    checklist:
-      - id: n-plus-one-queries
-        description: "No N+1 query patterns in list endpoints. Use eager loading or DataLoader."
-        severity: critical
-      - id: pagination
-        description: "List endpoints paginated. No unbounded result sets."
-        severity: critical
-      - id: rate-limiting
-        description: "Rate limiting configured on all public-facing endpoints."
-        severity: important
-      - id: response-caching
-        description: "Cacheable responses use Cache-Control headers or application-level caching."
-        severity: nice-to-have
-
-  - id: api-test-review
-    tier: recommended
-    dimension: tests
-    title: "API Test Review"
-    description: |
-      Evaluate API-specific testing patterns including contract tests and migration testing.
-    checklist:
-      - id: migration-testing
-        description: "Database migrations tested: up + down both verified. Migration tests run in CI."
-        severity: critical
-      - id: api-contract-tests
-        description: "API contracts tested: request/response shapes match OpenAPI spec. Breaking changes caught early."
-        severity: important
-      - id: auth-path-testing
-        description: "Auth paths thoroughly tested: valid token, expired token, missing token, insufficient permissions."
-        severity: critical
+tag: API
+section: review
+blocks:
+  - id: api-architecture-review
+    tier: recommended
+    dimension: architecture
+    title: "API Architecture Review"
+    description: |
+      Evaluate API design, endpoint structure, middleware pipeline, and service boundaries.
+    checklist:
+      - id: endpoint-design
+        description: "RESTful conventions followed: proper HTTP methods, status codes, resource naming."
+        severity: critical
+      - id: middleware-pipeline
+        description: "Middleware pipeline is ordered correctly: auth → validation → rate-limit → handler."
+        severity: important
+      - id: service-layer-separation
+        description: "Handlers are thin (validation + delegation). Business logic lives in service layer."
+        severity: critical
+      - id: api-versioning
+        description: "API versioning strategy defined and enforced (URL prefix, header, or content negotiation)."
+        severity: important
+      - id: database-migrations
+        description: "Schema changes managed through versioned migration files. Every migration is reversible. No manual DDL."
+        severity: critical
+      - id: owasp-injection
+        description: "Parameterized queries only. No string concatenation for SQL, commands, or LDAP queries."
+        severity: critical
+      - id: owasp-access-control
+        description: "Ownership checks enforced — users cannot access other users' resources. No IDOR vulnerabilities."
+        severity: critical
+      - id: security-headers
+        description: "Security headers set: CSP, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy."
+        severity: important
+      - id: audit-logging
+        description: "Security-relevant actions logged: WHO did WHAT to WHICH resource, WHEN. Immutable, separate from app logs."
+        severity: important
+      - id: graceful-shutdown
+        description: "SIGTERM handled: stop accepting requests, drain in-flight work, close connections, exit cleanly."
+        severity: important
+      - id: container-best-practices
+        description: "Dockerfile uses multi-stage build, non-root user, pinned base image digest. Image scanned for CVEs."
+        severity: important
+      - id: health-endpoint
+        description: "/health endpoint returns status, version, uptime, and dependency connectivity. Used by orchestrator probes."
+        severity: critical
+      - id: migration-auto-deploy
+        description: "Database migrations run automatically on deploy (pre-deploy hook or init container). Never manually applied."
+        severity: important
+
+  - id: api-code-quality-review
+    tier: recommended
+    dimension: code-quality
+    title: "API Code Quality Review"
+    description: |
+      Evaluate input validation, response contracts, and error response consistency.
+    checklist:
+      - id: input-validation
+        description: "All endpoint inputs validated with schema (Zod, Joi, class-validator). No trust of client data."
+        severity: critical
+      - id: response-consistency
+        description: "All responses follow a consistent envelope: { data, error, meta }."
+        severity: important
+      - id: error-responses
+        description: "Error responses include: status code, error code, human message, request ID. No stack traces in production."
+        severity: critical
+
+  - id: api-performance-review
+    tier: recommended
+    dimension: performance
+    title: "API Performance Review"
+    description: |
+      Evaluate query efficiency, pagination, and rate limiting.
+    checklist:
+      - id: n-plus-one-queries
+        description: "No N+1 query patterns in list endpoints. Use eager loading or DataLoader."
+        severity: critical
+      - id: pagination
+        description: "List endpoints paginated. No unbounded result sets."
+        severity: critical
+      - id: rate-limiting
+        description: "Rate limiting configured on all public-facing endpoints."
+        severity: important
+      - id: response-caching
+        description: "Cacheable responses use Cache-Control headers or application-level caching."
+        severity: nice-to-have
+
+  - id: api-test-review
+    tier: recommended
+    dimension: tests
+    title: "API Test Review"
+    description: |
+      Evaluate API-specific testing patterns including contract tests and migration testing.
+    checklist:
+      - id: migration-testing
+        description: "Database migrations tested: up + down both verified. Migration tests run in CI."
+        severity: critical
+      - id: api-contract-tests
+        description: "API contracts tested: request/response shapes match OpenAPI spec. Breaking changes caught early."
+        severity: important
+      - id: auth-path-testing
+        description: "Auth paths thoroughly tested: valid token, expired token, missing token, insufficient permissions."
+        severity: critical

package/templates/api/structure.yaml

@@ -1,34 +1,34 @@
-tag: API
-section: structure
-language: typescript
-entries:
-  - path: src/index.ts
-    type: file
-    description: "Composition root — only place concretes are instantiated"
-  - path: src/shared/config/index.ts
-    type: file
-    description: "Env validation with fail-fast"
-  - path: src/shared/errors/index.ts
-    type: file
-    description: "Error class hierarchy"
-  - path: src/shared/logger/index.ts
-    type: file
-    description: "Structured logging (pino)"
-  - path: src/shared/middleware
-    type: directory
-    description: "Auth, error handler, request ID"
-  - path: src/shared/types
-    type: directory
-    description: "Shared interfaces and type definitions"
-  - path: src/modules
-    type: directory
-    description: "Feature modules"
-  - path: tests/unit
-    type: directory
-    description: "Unit tests"
-  - path: tests/integration
-    type: directory
-    description: "Integration tests"
-  - path: tests/e2e
-    type: directory
-    description: "End-to-end tests"
+tag: API
+section: structure
+language: typescript
+entries:
+  - path: src/index.ts
+    type: file
+    description: "Composition root — only place concretes are instantiated"
+  - path: src/shared/config/index.ts
+    type: file
+    description: "Env validation with fail-fast"
+  - path: src/shared/errors/index.ts
+    type: file
+    description: "Error class hierarchy"
+  - path: src/shared/logger/index.ts
+    type: file
+    description: "Structured logging (pino)"
+  - path: src/shared/middleware
+    type: directory
+    description: "Auth, error handler, request ID"
+  - path: src/shared/types
+    type: directory
+    description: "Shared interfaces and type definitions"
+  - path: src/modules
+    type: directory
+    description: "Feature modules"
+  - path: tests/unit
+    type: directory
+    description: "Unit tests"
+  - path: tests/integration
+    type: directory
+    description: "Integration tests"
+  - path: tests/e2e
+    type: directory
+    description: "End-to-end tests"

package/templates/api/verification.yaml

@@ -1,132 +1,132 @@
-tag: API
-section: verification
-title: "Spec-Driven API Verification"
-description: >
-  API contracts are the highest-determinism domain. A formal Hurl spec or
-  OpenAPI schema covers every endpoint, method, status code, and response shape.
-  When this strategy is applied, S approaches 1.0 — enabling single-pass
-  automated verification with no human judgment required at execution time.
-uncertainty_levels:
-  - deterministic
-completeness_ceiling: 0.95
-
-phases:
-
-  - id: contract-definition
-    title: "Define the API Contract Before Code"
-    rationale: >
-      The OpenAPI spec is the source of truth. Types, validators, and tests
-      must be generated from it — never maintained in parallel. A spec written
-      before implementation is a contract; a spec written after implementation
-      is documentation.
-    steps:
-      - id: write-openapi-spec
-        instruction: >
-          Write the full OpenAPI 3.1 spec for every endpoint before implementation.
-          Every endpoint must define: path, method, request schema (body + query + path params),
-          all response codes with response schemas, and security requirements.
-          Use $ref for shared schemas — no inline duplication.
-        contract: >
-          openapi.yaml or openapi.json exists in the project root and passes
-          `openapi-spec-validator`. Every endpoint in the spec maps 1:1 to a route
-          in the implementation.
-        tools: ["openapi-spec-validator", "stoplight/spectral"]
-        expected_output: "openapi.yaml validated by openapi-spec-validator with 0 errors"
-        pass_criterion: "openapi-spec-validator openapi.yaml exits 0"
-
-      - id: generate-types-from-spec
-        instruction: >
-          Generate TypeScript types from the OpenAPI spec using openapi-typescript.
-          Use the generated types in route handlers and service layers — do not
-          hand-write types that duplicate the spec.
-        contract: >
-          src/types/api.ts (or equivalent) is generated, not hand-written.
-          A Makefile or package.json script exists to regenerate it.
-        tools: ["openapi-typescript", "npx openapi-typescript openapi.yaml -o src/types/api.ts"]
-        expected_output: "Generated src/types/api.ts with no manual edits"
-        pass_criterion: "File is generated; `npm run generate-types` succeeds"
-
-      - id: write-hurl-spec
-        instruction: >
-          Write a Hurl spec file for every endpoint. Each file covers:
-          the happy path, at least one error case (400/401/403/404/422),
-          and one edge case (e.g., empty list, max payload).
-          Variables use Hurl's {{variable}} syntax for base_url, tokens, etc.
-        contract: >
-          A .hurl file exists per endpoint group (auth, articles, users, etc.).
-          Total Hurl files ≥ number of resource groups. Every Hurl file runs
-          to completion without network errors.
-        tools: ["hurl --test", "hurl --variables-file .env.test"]
-        expected_output: "Hurl test output with pass/fail per file"
-        pass_criterion: "hurl --test *.hurl exits 0 with 0 failures"
-
-  - id: execution
-    title: "Run Hurl Spec Against Live Server"
-    rationale: >
-      The gap between GS Verifiable and Executable is closed here. The server must be
-      running with a test database. Hurl drives real HTTP — it catches route wiring gaps,
-      JWT issues, and normalization bugs that no unit test can detect.
-    steps:
-      - id: start-server
-        instruction: >
-          Start the API server with NODE_ENV=test and a clean test database.
-          Sync the schema with `prisma db push --accept-data-loss` (not `migrate deploy` —
-          migrate deploy silently no-ops when no migrations folder exists, leaving an empty DB).
-          Capture the server process and its port in a test fixture.
-        contract: >
-          Server health check endpoint returns HTTP 200 within 5 seconds.
-          Test database has 0 seed rows (clean state).
-        tools: ["docker-compose up -d", "npx prisma db push --accept-data-loss", "curl /health"]
-        expected_output: "HTTP 200 from /health or /api/health"
-        pass_criterion: "curl -s localhost:PORT/health returns 200"
-
-      - id: run-hurl-suite
-        instruction: >
-          Run all Hurl files in sequence. Record: total files, total assertions,
-          pass count, fail count. For every failure, capture: file name, step number,
-          expected vs actual response body and status code.
-        contract: >
-          ≥ 80% of Hurl files pass. 100% of auth-related files pass.
-          Zero 5xx responses on any happy-path request.
-        tools: ["hurl --test --report-junit junit-hurl.xml", "hurl --variables-file .env.test"]
-        expected_output: "JUnit XML + terminal summary: N files, M passed, K failed"
-        pass_criterion: "Pass rate ≥ 80%; 0 failures in auth.hurl"
-
-      - id: run-schema-validator
-        instruction: >
-          For every response captured by the Hurl run, validate the response body against
-          the OpenAPI spec's response schema. Use `openapi-backend` or `express-openapi-validator`
-          in strict mode. Treat schema mismatches as failures even if Hurl assertions passed.
-        contract: >
-          0 schema validation errors. Response shapes match spec exactly —
-          no extra undocumented fields, no missing required fields.
-        tools: ["openapi-backend", "express-openapi-validator"]
-        expected_output: "Validation report with 0 mismatches"
-        pass_criterion: "0 schema validation errors"
-
-  - id: evidence
-    title: "Record and Interpret Execution Results"
-    rationale: >
-      Hurl results feed directly into the Executable dimension score (0–2).
-      Results must be structured so the verify loop can detect regressions
-      across passes and determine whether the fix prompt improved things.
-    steps:
-      - id: record-hurl-results
-        instruction: >
-          Save the JUnit XML report to test-results/hurl-junit.xml.
-          Extract: total files count, pass count, fail count, failed file names.
-          Write a one-line summary to test-results/hurl-summary.txt.
-        contract: "test-results/hurl-junit.xml and hurl-summary.txt exist after run"
-        tools: ["hurl --report-junit", "xsltproc or python xml.etree"]
-        expected_output: "hurl-summary.txt: '13 files, 12 passed, 1 failed'"
-        pass_criterion: "Files exist; pass count parseable as integer"
-
-      - id: compute-executable-score
-        instruction: >
-          Compute the Executable score: 0 if server fails to start, 1 if 1–79% of Hurl files pass,
-          2 if ≥ 80% of Hurl files pass. Record this score in test-results/executable-score.json
-          with fields: score, pass_rate, total_files, passed_files, timestamp.
-        contract: "executable-score.json exists with integer score 0|1|2"
-        tools: ["node -e", "python -c", "jq"]
-        expected_output: '{"score": 2, "pass_rate": 0.92, "total_files": 13, "passed_files": 12}'
-        pass_criterion: "File parses as valid JSON with score field"
+tag: API
+section: verification
+title: "Spec-Driven API Verification"
+description: >
+  API contracts are the highest-determinism domain. A formal Hurl spec or
+  OpenAPI schema covers every endpoint, method, status code, and response shape.
+  When this strategy is applied, S approaches 1.0 — enabling single-pass
+  automated verification with no human judgment required at execution time.
+uncertainty_levels:
+  - deterministic
+completeness_ceiling: 0.95
+
+phases:
+
+  - id: contract-definition
+    title: "Define the API Contract Before Code"
+    rationale: >
+      The OpenAPI spec is the source of truth. Types, validators, and tests
+      must be generated from it — never maintained in parallel. A spec written
+      before implementation is a contract; a spec written after implementation
+      is documentation.
+    steps:
+      - id: write-openapi-spec
+        instruction: >
+          Write the full OpenAPI 3.1 spec for every endpoint before implementation.
+          Every endpoint must define: path, method, request schema (body + query + path params),
+          all response codes with response schemas, and security requirements.
+          Use $ref for shared schemas — no inline duplication.
+        contract: >
+          openapi.yaml or openapi.json exists in the project root and passes
+          `openapi-spec-validator`. Every endpoint in the spec maps 1:1 to a route
+          in the implementation.
+        tools: ["openapi-spec-validator", "stoplight/spectral"]
+        expected_output: "openapi.yaml validated by openapi-spec-validator with 0 errors"
+        pass_criterion: "openapi-spec-validator openapi.yaml exits 0"
+
+      - id: generate-types-from-spec
+        instruction: >
+          Generate TypeScript types from the OpenAPI spec using openapi-typescript.
+          Use the generated types in route handlers and service layers — do not
+          hand-write types that duplicate the spec.
+        contract: >
+          src/types/api.ts (or equivalent) is generated, not hand-written.
+          A Makefile or package.json script exists to regenerate it.
+        tools: ["openapi-typescript", "npx openapi-typescript openapi.yaml -o src/types/api.ts"]
+        expected_output: "Generated src/types/api.ts with no manual edits"
+        pass_criterion: "File is generated; `npm run generate-types` succeeds"
+
+      - id: write-hurl-spec
+        instruction: >
+          Write a Hurl spec file for every endpoint. Each file covers:
+          the happy path, at least one error case (400/401/403/404/422),
+          and one edge case (e.g., empty list, max payload).
+          Variables use Hurl's {{variable}} syntax for base_url, tokens, etc.
+        contract: >
+          A .hurl file exists per endpoint group (auth, articles, users, etc.).
+          Total Hurl files ≥ number of resource groups. Every Hurl file runs
+          to completion without network errors.
+        tools: ["hurl --test", "hurl --variables-file .env.test"]
+        expected_output: "Hurl test output with pass/fail per file"
+        pass_criterion: "hurl --test *.hurl exits 0 with 0 failures"
+
+  - id: execution
+    title: "Run Hurl Spec Against Live Server"
+    rationale: >
+      The gap between GS Verifiable and Executable is closed here. The server must be
+      running with a test database. Hurl drives real HTTP — it catches route wiring gaps,
+      JWT issues, and normalization bugs that no unit test can detect.
+    steps:
+      - id: start-server
+        instruction: >
+          Start the API server with NODE_ENV=test and a clean test database.
+          Sync the schema with `prisma db push --accept-data-loss` (not `migrate deploy` —
+          migrate deploy silently no-ops when no migrations folder exists, leaving an empty DB).
+          Capture the server process and its port in a test fixture.
+        contract: >
+          Server health check endpoint returns HTTP 200 within 5 seconds.
+          Test database has 0 seed rows (clean state).
+        tools: ["docker-compose up -d", "npx prisma db push --accept-data-loss", "curl /health"]
+        expected_output: "HTTP 200 from /health or /api/health"
+        pass_criterion: "curl -s localhost:PORT/health returns 200"
+
+      - id: run-hurl-suite
+        instruction: >
+          Run all Hurl files in sequence. Record: total files, total assertions,
+          pass count, fail count. For every failure, capture: file name, step number,
+          expected vs actual response body and status code.
+        contract: >
+          ≥ 80% of Hurl files pass. 100% of auth-related files pass.
+          Zero 5xx responses on any happy-path request.
+        tools: ["hurl --test --report-junit junit-hurl.xml", "hurl --variables-file .env.test"]
+        expected_output: "JUnit XML + terminal summary: N files, M passed, K failed"
+        pass_criterion: "Pass rate ≥ 80%; 0 failures in auth.hurl"
+
+      - id: run-schema-validator
+        instruction: >
+          For every response captured by the Hurl run, validate the response body against
+          the OpenAPI spec's response schema. Use `openapi-backend` or `express-openapi-validator`
+          in strict mode. Treat schema mismatches as failures even if Hurl assertions passed.
+        contract: >
+          0 schema validation errors. Response shapes match spec exactly —
+          no extra undocumented fields, no missing required fields.
+        tools: ["openapi-backend", "express-openapi-validator"]
+        expected_output: "Validation report with 0 mismatches"
+        pass_criterion: "0 schema validation errors"
+
+  - id: evidence
+    title: "Record and Interpret Execution Results"
+    rationale: >
+      Hurl results feed directly into the Executable dimension score (0–2).
+      Results must be structured so the verify loop can detect regressions
+      across passes and determine whether the fix prompt improved things.
+    steps:
+      - id: record-hurl-results
+        instruction: >
+          Save the JUnit XML report to test-results/hurl-junit.xml.
+          Extract: total files count, pass count, fail count, failed file names.
+          Write a one-line summary to test-results/hurl-summary.txt.
+        contract: "test-results/hurl-junit.xml and hurl-summary.txt exist after run"
+        tools: ["hurl --report-junit", "xsltproc or python xml.etree"]
+        expected_output: "hurl-summary.txt: '13 files, 12 passed, 1 failed'"
+        pass_criterion: "Files exist; pass count parseable as integer"
+
+      - id: compute-executable-score
+        instruction: >
+          Compute the Executable score: 0 if server fails to start, 1 if 1–79% of Hurl files pass,
+          2 if ≥ 80% of Hurl files pass. Record this score in test-results/executable-score.json
+          with fields: score, pass_rate, total_files, passed_files, timestamp.
+        contract: "executable-score.json exists with integer score 0|1|2"
+        tools: ["node -e", "python -c", "jq"]
+        expected_output: '{"score": 2, "pass_rate": 0.92, "total_files": 13, "passed_files": 12}'
+        pass_criterion: "File parses as valid JSON with score field"