forgecraft-mcp 1.4.0 → 1.7.0

package/templates/analytics/instructions.yaml

@@ -1,37 +1,37 @@
-tag: ANALYTICS
-section: instructions
-blocks:
-  - id: analytics-architecture
-    tier: recommended
-    title: "Analytics & Data Warehouse Standards"
-    content: |
-      ## Analytics & Data Warehouse Standards
-
-      ### Architecture — Separation of Concerns
-      Operational database and analytical database are SEPARATE systems. Never run analytical
-      queries against your production OLTP database.
-
-      ### Event Collection — Instrument Everything
-      - Every significant user action and system event emits a structured event.
-      - Events are immutable, append-only, timestamped, and include context.
-      - Event schema versioned — schema registry or embedded version field.
-      - Events flow through a pipeline: collect → validate → enrich → store → aggregate.
-      - NO direct writes to analytical store from application code.
-
-      ### Aggregation Layers
-      Raw events are for debugging and backfilling. Everything else reads from aggregations.
-
-      | Layer | Granularity | Refresh | Use Case |
-      |-------|------------|---------|----------|
-      | Real-time | Per-event or 1-min | Streaming | Live dashboards, alerts |
-      | Hourly | 1-hour buckets | Scheduled | Operational dashboards |
-      | Daily | 1-day buckets | Nightly | Business reports, KPIs |
-      | Weekly/Monthly | Week/month | Scheduled | Executive reporting |
-
-      ### Reporting
-      - Dashboards read ONLY from aggregated views.
-      - Three tiers: Operational (real-time), Tactical (daily), Strategic (weekly/monthly).
-
-      ### Signals & Prediction
-      - Signals are pre-computed and stored, not computed on-demand.
-      - Every signal has: value, confidence, computed_at, TTL/expiry.
+tag: ANALYTICS
+section: instructions
+blocks:
+  - id: analytics-architecture
+    tier: recommended
+    title: "Analytics & Data Warehouse Standards"
+    content: |
+      ## Analytics & Data Warehouse Standards
+
+      ### Architecture — Separation of Concerns
+      Operational database and analytical database are SEPARATE systems. Never run analytical
+      queries against your production OLTP database.
+
+      ### Event Collection — Instrument Everything
+      - Every significant user action and system event emits a structured event.
+      - Events are immutable, append-only, timestamped, and include context.
+      - Event schema versioned — schema registry or embedded version field.
+      - Events flow through a pipeline: collect → validate → enrich → store → aggregate.
+      - NO direct writes to analytical store from application code.
+
+      ### Aggregation Layers
+      Raw events are for debugging and backfilling. Everything else reads from aggregations.
+
+      | Layer | Granularity | Refresh | Use Case |
+      |-------|------------|---------|----------|
+      | Real-time | Per-event or 1-min | Streaming | Live dashboards, alerts |
+      | Hourly | 1-hour buckets | Scheduled | Operational dashboards |
+      | Daily | 1-day buckets | Nightly | Business reports, KPIs |
+      | Weekly/Monthly | Week/month | Scheduled | Executive reporting |
+
+      ### Reporting
+      - Dashboards read ONLY from aggregated views.
+      - Three tiers: Operational (real-time), Tactical (daily), Strategic (weekly/monthly).
+
+      ### Signals & Prediction
+      - Signals are pre-computed and stored, not computed on-demand.
+      - Every signal has: value, confidence, computed_at, TTL/expiry.

package/templates/analytics/mcp-servers.yaml

@@ -1,11 +1,11 @@
-tag: ANALYTICS
-section: mcp-servers
-servers:
-  - name: chrome-devtools
-    description: "Chrome DevTools integration for debugging, profiling, and network inspection"
-    command: npx
-    args: ["-y", "@anthropic/chrome-devtools-mcp@latest"]
-    tags: [WEB-REACT, WEB-STATIC, ANALYTICS]
-    category: devtools
-    tier: recommended
-    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp"
+tag: ANALYTICS
+section: mcp-servers
+servers:
+  - name: chrome-devtools
+    description: "Chrome DevTools integration for debugging, profiling, and network inspection"
+    command: npx
+    args: ["-y", "@anthropic/chrome-devtools-mcp@latest"]
+    tags: [WEB-REACT, WEB-STATIC, ANALYTICS]
+    category: devtools
+    tier: recommended
+    url: "https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp"

package/templates/analytics/structure.yaml

@@ -1,25 +1,25 @@
-tag: ANALYTICS
-section: structure
-language: typescript
-entries:
-  - path: src/analytics/events
-    type: directory
-    description: "Event type definitions, emitter, validator"
-  - path: src/analytics/events/schema.ts
-    type: file
-    description: "Typed, versioned event definitions"
-  - path: src/analytics/events/emitter.ts
-    type: file
-    description: "Event emission interface"
-  - path: src/analytics/pipeline
-    type: directory
-    description: "Event collection, processing, dead-letter"
-  - path: src/analytics/aggregations
-    type: directory
-    description: "Aggregation definitions and scheduling"
-  - path: src/analytics/signals
-    type: directory
-    description: "Pre-computed signal service"
-  - path: src/analytics/dashboards
-    type: directory
-    description: "Dashboard config as code"
+tag: ANALYTICS
+section: structure
+language: typescript
+entries:
+  - path: src/analytics/events
+    type: directory
+    description: "Event type definitions, emitter, validator"
+  - path: src/analytics/events/schema.ts
+    type: file
+    description: "Typed, versioned event definitions"
+  - path: src/analytics/events/emitter.ts
+    type: file
+    description: "Event emission interface"
+  - path: src/analytics/pipeline
+    type: directory
+    description: "Event collection, processing, dead-letter"
+  - path: src/analytics/aggregations
+    type: directory
+    description: "Aggregation definitions and scheduling"
+  - path: src/analytics/signals
+    type: directory
+    description: "Pre-computed signal service"
+  - path: src/analytics/dashboards
+    type: directory
+    description: "Dashboard config as code"

package/templates/api/harness/uc-template.hurl

@@ -0,0 +1,20 @@
+# L2 Harness: {{uc_id}} — {{uc_title}}
+# Actor: {{actor}}
+# Precondition: {{precondition}}
+# Postcondition: {{postcondition}}
+#
+# This is a behavioral harness probe. A failure is a specification violation.
+# Implement the main flow steps from the use case below.
+
+# Step 1: [precondition setup if needed]
+# POST http://{{host}}/api/auth/login
+# ...
+
+# Step 2: [primary action]
+# TODO: implement UC main flow as HTTP sequence
+GET http://{{host}}/api/endpoint
+Authorization: Bearer {{token}}
+
+HTTP 200
+[Asserts]
+# jsonpath "$.field" == "expected_value"

package/templates/api/instructions.yaml

@@ -1,231 +1,231 @@
-tag: API
-section: instructions
-blocks:
-  - id: api-standards
-    tier: recommended
-    title: "API Service Standards"
-    content: |
-      ## API Standards
-
-      ### Contract First
-      - Define OpenAPI/JSON Schema spec before implementing endpoints.
-      - Generate types from spec — don't manually duplicate.
-      - Spec is the source of truth. Implementation must match.
-
-      ### Design Rules
-      - Version from day one: /api/v1/...
-      - Proper HTTP semantics: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes.
-      - Pagination on ALL list endpoints. Never return unbounded results.
-      - Consistent response envelope: { data, meta, errors }.
-      - Async operations return job ID + polling endpoint, not blocking results.
-      - Rate limiting on all public endpoints.
-
-      ### Validation
-      - Input validation at API boundary — reject malformed requests before they reach services.
-      - Use schema validation (Pydantic, Zod, Joi) not manual if-checks.
-      - Validate request body, query params, path params, and headers.
-      - Return 422 with specific field errors, not generic 400.
-
-      ### Authentication & Authorization
-      - Auth middleware/guards at router level, not checked inside handlers.
-      - Role-based or policy-based access control via decorators/middleware.
-      - Never trust client-sent user identity — always verify from token/session.
-
-      ### Database & Migrations
-      - Schema changes managed through migration files (Prisma Migrate, Knex, Flyway, Alembic).
-      - Every migration must be reversible (up + down). Test rollbacks.
-      - Never modify a deployed migration — create a new one.
-      - Seed data separate from migrations. Test seeds run in CI.
-
-      ### Security (OWASP Top 10)
-      - **Injection**: Parameterized queries only. No string concatenation for SQL, commands, or LDAP.
-      - **Broken Auth**: Rate-limit login attempts. Enforce strong passwords. Rotate tokens.
-      - **Sensitive Data Exposure**: Encrypt at rest (AES-256). Never log PII, tokens, or passwords.
-      - **XXE/XSS**: Sanitize all user-generated HTML. Content-Security-Policy headers on all responses.
-      - **Broken Access Control**: Enforce ownership checks — users can't access other users' resources.
-      - **Security Misconfiguration**: No default credentials. No verbose error messages in production.
-        Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
-      - **CSRF**: Token-based protection on all state-changing endpoints (unless using SameSite cookies + bearer tokens).
-      - **Audit logging**: Log WHO did WHAT, WHEN, to WHICH resource. Separate from application logs.
-        Immutable. Retained per compliance requirements.
-
-      ### Graceful Shutdown
-      - Handle SIGTERM: stop accepting new requests, drain in-flight requests, close DB connections, exit.
-      - Kubernetes: readiness probe fails immediately, liveness continues during drain.
-      - Shutdown timeout configurable (default: 30s). Force exit after timeout.
-
-  - id: api-stack-constraints
-    tier: core
-    title: "API Stack Constraints"
-    content: |
-      ## API Stack Constraints — Approved Dependency Choices
-
-      These are the **approved libraries for this API project**.
-      Every choice has a banned alternative with a concrete reason.
-      If you reach for a banned alternative, stop and use the approved one instead.
-      Rationale is stated so you understand the constraint — not so you can argue around it.
-
-      {{#if language_is_typescript}}
-      ### TypeScript API — Required Packages
-
-      | Concern | Use | Do NOT use | Reason |
-      |---|---|---|---|
-      | **Password hashing** | `argon2@^0.31` | `bcrypt`, `bcryptjs` | `bcrypt` requires a native module (`@mapbox/node-pre-gyp`) that pulls in an old `tar` CVE chain. `argon2` is pure JS, faster, OWASP-preferred. |
-      | **HTTP framework** | `express@^4` or `fastify@^4` | `restify`, `hapi@<21`, `koa` alone | `restify` is unmaintained. `hapi` is fine at `^21+` only. |
-      | **Input validation** | `zod@^3` | `joi` alone, `express-validator` alone | `zod` infers TypeScript types natively — no separate type declaration needed. |
-      | **JWT** | `jsonwebtoken@^9` | `jwt-simple` (abandoned), `jsonwebtoken@<9` | Security fixes landed in v9. `jwt-simple` has no active maintainer. |
-      | **ORM / query builder** | `@prisma/client@^5` or `kysely@^0.27` | `typeorm`, `sequelize` | `typeorm` uses decorators (not type-safe), slow migrations. `sequelize` has weak TypeScript support. |
-      | **Logger** | `pino@^9` | `winston` alone, `console.log` in prod | `pino` is 5–10× faster than `winston` and outputs structured JSON natively. `console.log` is not structured. |
-      | **HTTP client (outbound)** | `undici@^6` or native `fetch` (Node 18+) | `axios` for Node ≥18 | Native `fetch` is available; `axios` adds bundle weight and a dependency surface for a built-in feature. |
-      | **ESLint** | `@typescript-eslint/eslint-plugin@^8` | `@typescript-eslint@^5` or `^6` | `^6` has a known CVE via old `minimatch` transitive dep. `^8` is the current stable. |
-
-      **npm audit policy**: `npm audit` must return zero `high` or `critical` findings before the
-      first commit. If a dependency introduces a high/critical CVE, replace it with an alternative
-      from this table or open an ADR documenting the exception with mitigation.
-      {{/if}}
-
-      {{#if language_is_python}}
-      ### Python API — Required Packages
-
-      | Concern | Use | Do NOT use | Reason |
-      |---|---|---|---|
-      | **Web framework** | `fastapi@^0.110` | `flask` for new async APIs | Flask has no native `async` request handling at the framework level — blocks on every request without extra extensions. |
-      | **Validation** | `pydantic@^2` | `pydantic@^1` | v2 is 5–50× faster. v1 is not maintained for new projects. Breaking API — pin to `^2`. |
-      | **Password hashing** | `argon2-cffi@^23` | `hashlib` for passwords, `MD5/SHA256` for passwords | `hashlib` is not a KDF — it is trivially reversible with a GPU. `argon2` wins OWASP Password Hashing Competition. |
-      | **JWT** | `PyJWT@^2.8` or `python-jose[cryptography]@^3.3` | `python-jwt` (unmaintained), `itsdangerous` alone | `python-jwt` has no active maintainer. `itsdangerous` is for URL-safe tokens, not JWT. |
-      | **ORM** | `sqlalchemy@^2.0` with `asyncpg` | `sqlalchemy@^1.x` | v2 has a fundamentally better async story and type-annotated query API. |
-      | **HTTP client** | `httpx@^0.27` | `requests` in async code | `requests` is sync-only — it will block the asyncio event loop. |
-      | **Logger** | `structlog@^24` | bare `logging` module in production | Unstructured log lines are not machine-parseable. `structlog` wraps `logging` with structured output. |
-      | **Linting** | `ruff@^0.4` | `flake8` + `isort` + `black` separately | `ruff` replaces all three with one tool 10–100× faster. No reason to run them separately. |
-
-      **pip audit policy**: `pip audit` must return zero `high` or `critical` findings before the
-      first commit. If a dependency introduces a high/critical CVE, replace it or open an ADR.
-      {{/if}}
-
-  - id: api-deployment
-    tier: recommended
-    title: "API Deployment & Hosting"
-    content: |
-      ## API Deployment
-
-      ### Container-Based (Production)
-      - Multi-stage Dockerfile: builder stage (install + compile) → runtime stage (minimal image, non-root).
-      - Pin base image digests, not just tags. Scan images for CVEs in CI (Trivy, Grype).
-      - Push to container registry (ECR, GCR, GHCR) on every merge to main.
-      - Orchestrate with Kubernetes, ECS, or Cloud Run. Define resource limits for every container.
-
-      ### PaaS / Quick Deploy
-      - **Railway**: Git-push deploy with auto-detected Dockerfile or Nixpacks. Ideal for staging and side projects.
-      - **Render**: Free tier + auto-deploy from Git. Native cron jobs, managed Postgres.
-      - **Fly.io**: Edge deployment with Firecracker VMs. Good for low-latency APIs. `fly deploy` from CI.
-      - All PaaS platforms: use platform env vars for secrets, connect managed DB add-ons, enable auto-sleep
-        for non-production to control cost.
-
-      ### Environment Management
-      - One Dockerfile, many environments. Same image runs in dev, staging, prod.
-      - Health check endpoint (`/health`) returns: status, version, uptime, dependency connectivity.
-      - Database connection pooling configured per environment (dev: 5, staging: 20, prod: 50+).
-      - Migrations run automatically on deploy (pre-deploy hook or init container). Never manually.
-
-  - id: api-testing
-    tier: recommended
-    title: "API-Specific Testing Requirements"
-    content: |
-      ## API-Specific Testing Requirements
-
-      ### Contract / Consumer-Driven Contract (CDC) — Mandatory
-      CDC is not optional for API projects. The consumer writes the pact file; the provider verifies it in CI before deployment. API breakage that passes all provider-side tests but fails consumers is the exact class of defect CDC prevents.
-      - Use Pact or Spring Cloud Contract.
-      - Pact broker (self-hosted or pactflow.io) stores pact files and verification results.
-      - Provider verification runs in CI on every build — a failed verification blocks deployment.
-      - CDC covers request schema, response schema, status codes, and error shapes. It does not cover load or security — those are separate gates.
-
-      ### API / Subcutaneous Tests as Primary Integration Layer
-      The subcutaneous layer (HTTP requests to a running server with real DB and stubbed external deps) is the primary integration verification surface for API projects. Unit tests verify logic; subcutaneous tests verify contracts.
-      - Use Supertest (Node) or httpx/pytest (Python) against a locally started server instance.
-      - Stub external services with WireMock, msw, or responses (Python). Never call real external APIs in CI.
-      - Every public endpoint has a subcutaneous test for: 200 happy path, 4xx validation rejection, 401/403 auth enforcement, and at least one edge case.
-
-      ### DAST at Staging — Mandatory
-      Dynamic application security testing is required before every production promotion. OWASP ZAP minimum.
-      - Run ZAP active scan against the staging environment as a post-deploy CI step.
-      - Define an acceptable risk threshold in the spec: which finding severities are blocking (High = always blocking; Medium/Low = tracked, not blocking by default).
-      - ZAP scan configuration committed to the repo (`zap-config.yaml`). Not a one-off manual step.
-
-      ### Rate Limiting and Throttling in Integration Layer
-      - Rate limit behavior must be covered in the subcutaneous integration suite, not just documented.
-      - Test: normal traffic (no throttle), burst traffic (trigger rate limit, receive 429), retry-after header present and correct.
-      - Test quota exhaustion and quota reset behavior for API-key-based limits.
-
-
-      ### Scaling
-      - Horizontal scaling by default. No in-memory session state — use Redis or DB.
-      - Auto-scaling rules based on CPU + request queue depth, not just CPU alone.
-      - Database read replicas for read-heavy workloads. Connection pooler (PgBouncer) in front of Postgres.
-
-  - id: api-smoke-testing
-    tier: recommended
-    title: "API Smoke Testing (Post-Deploy)"
-    content: |
-      ## API Smoke Testing
-
-      ### Required: Playwright APIRequestContext (no browser overhead)
-      Tag all smoke tests `@smoke` for isolated execution:
-      ```
-      npx playwright test --config playwright.smoke.config.ts --grep @smoke
-      ```
-
-      Minimum smoke suite for every API:
-      - **Health check**: `GET /health` → 200, body includes `status: ok` and `version`
-      - **Auth**: primary login endpoint with valid credentials → token returned
-      - **Primary read**: one representative `GET` → 200, response envelope validates
-      - **Primary write**: one representative `POST` → 2xx, verify with follow-up `GET`
-      - **404 shape**: non-existent resource → 404, error envelope matches spec contract
-
-      ```typescript
-      // tests/smoke/api.smoke.ts
-      import { test, expect } from '@playwright/test';
-
-      test('@smoke health check', async ({ request }) => {
-        const res = await request.get('/health');
-        expect(res.ok()).toBeTruthy();
-        const body = await res.json();
-        expect(body).toMatchObject({ status: 'ok' });
-      });
-
-      test('@smoke auth returns token', async ({ request }) => {
-        const res = await request.post('/api/v1/auth/login', {
-          data: {
-            email: process.env['SMOKE_USER'],
-            password: process.env['SMOKE_PASSWORD'],
-          },
-        });
-        expect(res.status()).toBe(200);
-        const body = await res.json();
-        expect(typeof body.token ?? body.data?.token).toBe('string');
-      });
-      ```
-
-      ```typescript
-      // playwright.smoke.config.ts
-      import { defineConfig } from '@playwright/test';
-      export default defineConfig({
-        use: { baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000' },
-        testMatch: '**/*.smoke.ts',
-        retries: 1,
-        timeout: 10_000,
-      });
-      ```
-
-      Smoke tests run against the **deployed staging URL** only (`PLAYWRIGHT_BASE_URL` env var).
-      They never run against localhost in CI — that is the integration suite's job.
-
-      CI integration (post-deploy step):
-      ```yaml
-      - name: Smoke Tests
-        run: npx playwright test --config playwright.smoke.config.ts
-        env:
-          PLAYWRIGHT_BASE_URL: ${{ env.STAGING_URL }}
-          SMOKE_USER: ${{ secrets.SMOKE_USER }}
-          SMOKE_PASSWORD: ${{ secrets.SMOKE_PASSWORD }}
-      ```
+tag: API
+section: instructions
+blocks:
+  - id: api-standards
+    tier: recommended
+    title: "API Service Standards"
+    content: |
+      ## API Standards
+
+      ### Contract First
+      - Define OpenAPI/JSON Schema spec before implementing endpoints.
+      - Generate types from spec — don't manually duplicate.
+      - Spec is the source of truth. Implementation must match.
+
+      ### Design Rules
+      - Version from day one: /api/v1/...
+      - Proper HTTP semantics: GET reads, POST creates, PUT replaces, PATCH updates, DELETE removes.
+      - Pagination on ALL list endpoints. Never return unbounded results.
+      - Consistent response envelope: { data, meta, errors }.
+      - Async operations return job ID + polling endpoint, not blocking results.
+      - Rate limiting on all public endpoints.
+
+      ### Validation
+      - Input validation at API boundary — reject malformed requests before they reach services.
+      - Use schema validation (Pydantic, Zod, Joi) not manual if-checks.
+      - Validate request body, query params, path params, and headers.
+      - Return 422 with specific field errors, not generic 400.
+
+      ### Authentication & Authorization
+      - Auth middleware/guards at router level, not checked inside handlers.
+      - Role-based or policy-based access control via decorators/middleware.
+      - Never trust client-sent user identity — always verify from token/session.
+
+      ### Database & Migrations
+      - Schema changes managed through migration files (Prisma Migrate, Knex, Flyway, Alembic).
+      - Every migration must be reversible (up + down). Test rollbacks.
+      - Never modify a deployed migration — create a new one.
+      - Seed data separate from migrations. Test seeds run in CI.
+
+      ### Security (OWASP Top 10)
+      - **Injection**: Parameterized queries only. No string concatenation for SQL, commands, or LDAP.
+      - **Broken Auth**: Rate-limit login attempts. Enforce strong passwords. Rotate tokens.
+      - **Sensitive Data Exposure**: Encrypt at rest (AES-256). Never log PII, tokens, or passwords.
+      - **XXE/XSS**: Sanitize all user-generated HTML. Content-Security-Policy headers on all responses.
+      - **Broken Access Control**: Enforce ownership checks — users can't access other users' resources.
+      - **Security Misconfiguration**: No default credentials. No verbose error messages in production.
+        Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy.
+      - **CSRF**: Token-based protection on all state-changing endpoints (unless using SameSite cookies + bearer tokens).
+      - **Audit logging**: Log WHO did WHAT, WHEN, to WHICH resource. Separate from application logs.
+        Immutable. Retained per compliance requirements.
+
+      ### Graceful Shutdown
+      - Handle SIGTERM: stop accepting new requests, drain in-flight requests, close DB connections, exit.
+      - Kubernetes: readiness probe fails immediately, liveness continues during drain.
+      - Shutdown timeout configurable (default: 30s). Force exit after timeout.
+
+  - id: api-stack-constraints
+    tier: core
+    title: "API Stack Constraints"
+    content: |
+      ## API Stack Constraints — Approved Dependency Choices
+
+      These are the **approved libraries for this API project**.
+      Every choice has a banned alternative with a concrete reason.
+      If you reach for a banned alternative, stop and use the approved one instead.
+      Rationale is stated so you understand the constraint — not so you can argue around it.
+
+      {{#if language_is_typescript}}
+      ### TypeScript API — Required Packages
+
+      | Concern | Use | Do NOT use | Reason |
+      |---|---|---|---|
+      | **Password hashing** | `argon2@^0.31` | `bcrypt`, `bcryptjs` | `bcrypt` requires a native module (`@mapbox/node-pre-gyp`) that pulls in an old `tar` CVE chain. `argon2` is pure JS, faster, OWASP-preferred. |
+      | **HTTP framework** | `express@^4` or `fastify@^4` | `restify`, `hapi@<21`, `koa` alone | `restify` is unmaintained. `hapi` is fine at `^21+` only. |
+      | **Input validation** | `zod@^3` | `joi` alone, `express-validator` alone | `zod` infers TypeScript types natively — no separate type declaration needed. |
+      | **JWT** | `jsonwebtoken@^9` | `jwt-simple` (abandoned), `jsonwebtoken@<9` | Security fixes landed in v9. `jwt-simple` has no active maintainer. |
+      | **ORM / query builder** | `@prisma/client@^5` or `kysely@^0.27` | `typeorm`, `sequelize` | `typeorm` uses decorators (not type-safe), slow migrations. `sequelize` has weak TypeScript support. |
+      | **Logger** | `pino@^9` | `winston` alone, `console.log` in prod | `pino` is 5–10× faster than `winston` and outputs structured JSON natively. `console.log` is not structured. |
+      | **HTTP client (outbound)** | `undici@^6` or native `fetch` (Node 18+) | `axios` for Node ≥18 | Native `fetch` is available; `axios` adds bundle weight and a dependency surface for a built-in feature. |
+      | **ESLint** | `@typescript-eslint/eslint-plugin@^8` | `@typescript-eslint@^5` or `^6` | `^6` has a known CVE via old `minimatch` transitive dep. `^8` is the current stable. |
+
+      **npm audit policy**: `npm audit` must return zero `high` or `critical` findings before the
+      first commit. If a dependency introduces a high/critical CVE, replace it with an alternative
+      from this table or open an ADR documenting the exception with mitigation.
+      {{/if}}
+
+      {{#if language_is_python}}
+      ### Python API — Required Packages
+
+      | Concern | Use | Do NOT use | Reason |
+      |---|---|---|---|
+      | **Web framework** | `fastapi@^0.110` | `flask` for new async APIs | Flask has no native `async` request handling at the framework level — blocks on every request without extra extensions. |
+      | **Validation** | `pydantic@^2` | `pydantic@^1` | v2 is 5–50× faster. v1 is not maintained for new projects. Breaking API — pin to `^2`. |
+      | **Password hashing** | `argon2-cffi@^23` | `hashlib` for passwords, `MD5/SHA256` for passwords | `hashlib` is not a KDF — it is trivially reversible with a GPU. `argon2` wins OWASP Password Hashing Competition. |
+      | **JWT** | `PyJWT@^2.8` or `python-jose[cryptography]@^3.3` | `python-jwt` (unmaintained), `itsdangerous` alone | `python-jwt` has no active maintainer. `itsdangerous` is for URL-safe tokens, not JWT. |
+      | **ORM** | `sqlalchemy@^2.0` with `asyncpg` | `sqlalchemy@^1.x` | v2 has a fundamentally better async story and type-annotated query API. |
+      | **HTTP client** | `httpx@^0.27` | `requests` in async code | `requests` is sync-only — it will block the asyncio event loop. |
+      | **Logger** | `structlog@^24` | bare `logging` module in production | Unstructured log lines are not machine-parseable. `structlog` wraps `logging` with structured output. |
+      | **Linting** | `ruff@^0.4` | `flake8` + `isort` + `black` separately | `ruff` replaces all three with one tool 10–100× faster. No reason to run them separately. |
+
+      **pip audit policy**: `pip audit` must return zero `high` or `critical` findings before the
+      first commit. If a dependency introduces a high/critical CVE, replace it or open an ADR.
+      {{/if}}
+
+  - id: api-deployment
+    tier: recommended
+    title: "API Deployment & Hosting"
+    content: |
+      ## API Deployment
+
+      ### Container-Based (Production)
+      - Multi-stage Dockerfile: builder stage (install + compile) → runtime stage (minimal image, non-root).
+      - Pin base image digests, not just tags. Scan images for CVEs in CI (Trivy, Grype).
+      - Push to container registry (ECR, GCR, GHCR) on every merge to main.
+      - Orchestrate with Kubernetes, ECS, or Cloud Run. Define resource limits for every container.
+
+      ### PaaS / Quick Deploy
+      - **Railway**: Git-push deploy with auto-detected Dockerfile or Nixpacks. Ideal for staging and side projects.
+      - **Render**: Free tier + auto-deploy from Git. Native cron jobs, managed Postgres.
+      - **Fly.io**: Edge deployment with Firecracker VMs. Good for low-latency APIs. `fly deploy` from CI.
+      - All PaaS platforms: use platform env vars for secrets, connect managed DB add-ons, enable auto-sleep
+        for non-production to control cost.
+
+      ### Environment Management
+      - One Dockerfile, many environments. Same image runs in dev, staging, prod.
+      - Health check endpoint (`/health`) returns: status, version, uptime, dependency connectivity.
+      - Database connection pooling configured per environment (dev: 5, staging: 20, prod: 50+).
+      - Migrations run automatically on deploy (pre-deploy hook or init container). Never manually.
+
+  - id: api-testing
+    tier: recommended
+    title: "API-Specific Testing Requirements"
+    content: |
+      ## API-Specific Testing Requirements
+
+      ### Contract / Consumer-Driven Contract (CDC) — Mandatory
+      CDC is not optional for API projects. The consumer writes the pact file; the provider verifies it in CI before deployment. API breakage that passes all provider-side tests but fails consumers is the exact class of defect CDC prevents.
+      - Use Pact or Spring Cloud Contract.
+      - Pact broker (self-hosted or pactflow.io) stores pact files and verification results.
+      - Provider verification runs in CI on every build — a failed verification blocks deployment.
+      - CDC covers request schema, response schema, status codes, and error shapes. It does not cover load or security — those are separate gates.
+
+      ### API / Subcutaneous Tests as Primary Integration Layer
+      The subcutaneous layer (HTTP requests to a running server with real DB and stubbed external deps) is the primary integration verification surface for API projects. Unit tests verify logic; subcutaneous tests verify contracts.
+      - Use Supertest (Node) or httpx/pytest (Python) against a locally started server instance.
+      - Stub external services with WireMock, msw, or responses (Python). Never call real external APIs in CI.
+      - Every public endpoint has a subcutaneous test for: 200 happy path, 4xx validation rejection, 401/403 auth enforcement, and at least one edge case.
+
+      ### DAST at Staging — Mandatory
+      Dynamic application security testing is required before every production promotion. OWASP ZAP minimum.
+      - Run ZAP active scan against the staging environment as a post-deploy CI step.
+      - Define an acceptable risk threshold in the spec: which finding severities are blocking (High = always blocking; Medium/Low = tracked, not blocking by default).
+      - ZAP scan configuration committed to the repo (`zap-config.yaml`). Not a one-off manual step.
+
+      ### Rate Limiting and Throttling in Integration Layer
+      - Rate limit behavior must be covered in the subcutaneous integration suite, not just documented.
+      - Test: normal traffic (no throttle), burst traffic (trigger rate limit, receive 429), retry-after header present and correct.
+      - Test quota exhaustion and quota reset behavior for API-key-based limits.
+
+
+      ### Scaling
+      - Horizontal scaling by default. No in-memory session state — use Redis or DB.
+      - Auto-scaling rules based on CPU + request queue depth, not just CPU alone.
+      - Database read replicas for read-heavy workloads. Connection pooler (PgBouncer) in front of Postgres.
+
+  - id: api-smoke-testing
+    tier: recommended
+    title: "API Smoke Testing (Post-Deploy)"
+    content: |
+      ## API Smoke Testing
+
+      ### Required: Playwright APIRequestContext (no browser overhead)
+      Tag all smoke tests `@smoke` for isolated execution:
+      ```
+      npx playwright test --config playwright.smoke.config.ts --grep @smoke
+      ```
+
+      Minimum smoke suite for every API:
+      - **Health check**: `GET /health` → 200, body includes `status: ok` and `version`
+      - **Auth**: primary login endpoint with valid credentials → token returned
+      - **Primary read**: one representative `GET` → 200, response envelope validates
+      - **Primary write**: one representative `POST` → 2xx, verify with follow-up `GET`
+      - **404 shape**: non-existent resource → 404, error envelope matches spec contract
+
+      ```typescript
+      // tests/smoke/api.smoke.ts
+      import { test, expect } from '@playwright/test';
+
+      test('@smoke health check', async ({ request }) => {
+        const res = await request.get('/health');
+        expect(res.ok()).toBeTruthy();
+        const body = await res.json();
+        expect(body).toMatchObject({ status: 'ok' });
+      });
+
+      test('@smoke auth returns token', async ({ request }) => {
+        const res = await request.post('/api/v1/auth/login', {
+          data: {
+            email: process.env['SMOKE_USER'],
+            password: process.env['SMOKE_PASSWORD'],
+          },
+        });
+        expect(res.status()).toBe(200);
+        const body = await res.json();
+        expect(typeof body.token ?? body.data?.token).toBe('string');
+      });
+      ```
+
+      ```typescript
+      // playwright.smoke.config.ts
+      import { defineConfig } from '@playwright/test';
+      export default defineConfig({
+        use: { baseURL: process.env['PLAYWRIGHT_BASE_URL'] ?? 'http://localhost:3000' },
+        testMatch: '**/*.smoke.ts',
+        retries: 1,
+        timeout: 10_000,
+      });
+      ```
+
+      Smoke tests run against the **deployed staging URL** only (`PLAYWRIGHT_BASE_URL` env var).
+      They never run against localhost in CI — that is the integration suite's job.
+
+      CI integration (post-deploy step):
+      ```yaml
+      - name: Smoke Tests
+        run: npx playwright test --config playwright.smoke.config.ts
+        env:
+          PLAYWRIGHT_BASE_URL: ${{ env.STAGING_URL }}
+          SMOKE_USER: ${{ secrets.SMOKE_USER }}
+          SMOKE_PASSWORD: ${{ secrets.SMOKE_PASSWORD }}
+      ```