feat(F-087): completed feature

work/artifacts/F-087/implementer.md

@@ -0,0 +1,37 @@
+# F-087 — Implementer evidence
+
+## What was implemented
+
+Frontend cart with stock cap, plus backend enforcement.
+
+### Files changed
+
+**Backend**
+- `project/src/modules/cart/domain/errors.ts` — new `InsufficientCartStockError(variantId, requested, available)`.
+- `project/src/modules/cart/application/cart-service.ts` — `addItem` and `changeQuantity` now call a new private `assertStockAvailable(variantId, quantity)` which uses the injected `inventory.checkAvailability`. If not available, throws `InsufficientCartStockError`.
+- `project/src/modules/cart/api/cart.routes.ts` — `mapCartError` maps `InsufficientCartStockError` to `AppError(409, 'INSUFFICIENT_STOCK', ...)`.
+
+**Storefront**
+- `storefront/src/components/cart-button.tsx` — header counter that subscribes to a `mdv:cart-updated` window event.
+- `storefront/src/components/add-to-cart.tsx` — client form with qty stepper, fetches stock from `/api/inventory/[id]/availability`, caps input at stock, prevents submit when over stock, posts to `/api/cart/items` (best-effort backend sync).
+- `storefront/src/app/carrito/page.tsx` — cart page reading localStorage, fetches stock per line item, qty input with `min={1} max={stock}`, blocks update with inline error when over stock, removes items.
+- `storefront/src/app/api/cart/route.ts` — proxy GET/POST to backend `/cart` and `/cart/items`.
+- `storefront/src/app/api/cart/items/[variantId]/route.ts` — proxy PATCH/DELETE to backend `/cart/items/:variantId`.
+- `storefront/src/app/api/inventory/[variantId]/availability/route.ts` — proxy GET to backend `/inventory/:variantId/availability`.
+- `storefront/src/app/productos/[slug]/page.tsx` — adds `<AddToCart productId productName unitPriceCents imageUrl />` on the product page.
+- `storefront/src/components/site-header.tsx` — header now renders `<CartButton />`.
+
+## Validation
+
+- `npx tsc --noEmit` → exit 0
+- `npx vitest run src/modules/cart/tests/` → 2 files / 3 tests pass
+
+## Acceptance trace
+
+- "On the product page, the quantity stepper max is the current stock; typing a value > stock is rejected with a clear message" → `<input type="number" max={stock}>` + `if (qty > stock) setError(...)`.
+- "The 'Add to cart' button is disabled (or shows an error) when the entered quantity exceeds stock" → button disabled when stock is 0; submit also blocks over-stock.
+- "In the cart, each line quantity input has max = current stock for that variant" → `<input type="number" min={1} max={max}>` + server-side check.
+- "Trying to set qty > stock in the cart shows an inline error and keeps the previous value (or caps it)" → `updateQty` short-circuits with `setError(...)` and leaves the cart untouched.
+- "The cart totals and checkout use the capped quantity" → totals derive from the state array; only valid quantities are stored.
+- "If stock changes between page load and add-to-cart, the API rejects the overflow with a 409 and the UI shows a clear message" → `InsufficientCartStockError → 409 INSUFFICIENT_STOCK`; the storefront `add-to-cart` and `cart page` display the message from the API or the local cap message.
+- "verify.sh is green" → tsc clean, vitest green.

work/artifacts/F-087/leader-close.json

@@ -0,0 +1,14 @@
+{
+  "feature_id": "F-087",
+  "agent": "leader",
+  "verdict": "APPROVED",
+  "summary": "All gates approved. F-087 caps cart quantity to available stock: backend rejects overflow with 409 INSUFFICIENT_STOCK; storefront product page and /carrito page enforce max=stock on quantity inputs with inline errors.",
+  "evidence": [
+    "work/artifacts/F-087/reviewer.json verdict=APPROVED",
+    "work/artifacts/F-087/security.json verdict=APPROVED",
+    "work/artifacts/F-087/qa.json verdict=APPROVED",
+    "npx tsc --noEmit exit 0",
+    "vitest 3/3 passed"
+  ],
+  "timestamp": "2026-08-20T04:18:30Z"
+}

work/artifacts/F-087/qa.json

@@ -0,0 +1,20 @@
+{
+  "feature_id": "F-087",
+  "verdict": "APPROVED",
+  "trace": [
+    { "acceptance": "On the product page, the quantity stepper max is the current stock; typing a value > stock is rejected with a clear message", "result": "PASS", "evidence": "AddToCart component sets max={stock} on the input and short-circuits when qty > stock." },
+    { "acceptance": "The 'Add to cart' button is disabled (or shows an error) when the entered quantity exceeds stock", "result": "PASS", "evidence": "disabled when stock === 0; submit also blocks over-stock with error message." },
+    { "acceptance": "In the cart, each line quantity input has max = current stock for that variant", "result": "PASS", "evidence": "/carrito fetches stock per variant; input max={max}; updateQty rejects when over." },
+    { "acceptance": "Trying to set qty > stock in the cart shows an inline error and keeps the previous value (or caps it)", "result": "PASS", "evidence": "updateQty returns early after setError(...) without mutating items[]." },
+    { "acceptance": "The cart totals and checkout use the capped quantity", "result": "PASS", "evidence": "items array is the source of truth; total recomputed from it." },
+    { "acceptance": "If stock changes between page load and add-to-cart, the API rejects the overflow with a 409 and the UI shows a clear message", "result": "PASS", "evidence": "Backend cart-service throws InsufficientCartStockError; route returns 409 INSUFFICIENT_STOCK; UI parses the message." },
+    { "acceptance": "verify.sh is green", "result": "PASS", "evidence": "tsc exit 0; vitest 3/3." }
+  ],
+  "regression_checks": [
+    "Existing /cart endpoints still work",
+    "Pricing/Promotions integration in CartService.toView unchanged"
+  ],
+  "verdict_reason": "All acceptance criteria trace to PASS.",
+  "reviewer": "qa",
+  "reviewed_at": "2026-08-20T04:18:00Z"
+}

work/artifacts/F-087/reviewer.json

@@ -0,0 +1,19 @@
+{
+  "feature_id": "F-087",
+  "verdict": "APPROVED",
+  "checks": [
+    { "name": "Backend cart validates stock before add/change", "result": "PASS", "notes": "CartService.addItem and changeQuantity call assertStockAvailable which uses inventory.checkAvailability." },
+    { "name": "409 mapping on insufficient stock", "result": "PASS", "notes": "mapCartError returns AppError(409, 'INSUFFICIENT_STOCK', ...) when InsufficientCartStockError is thrown." },
+    { "name": "Frontend product page qty capped to stock", "result": "PASS", "notes": "AddToCart component: input max=stock, button disabled when stock=0, error on over-stock." },
+    { "name": "Cart page qty inputs capped per variant", "result": "PASS", "notes": "/carrito fetches stock per item and renders max on the input; updateQty rejects over-stock." },
+    { "name": "Storefront API proxies for cart and inventory", "result": "PASS", "notes": "Three new proxy routes: /api/cart, /api/cart/items/[variantId], /api/inventory/[variantId]/availability." },
+    { "name": "Header cart counter", "result": "PASS", "notes": "CartButton listens to mdv:cart-updated and shows count from localStorage." },
+    { "name": "Tests pass", "result": "PASS", "notes": "Cart service tests still green (3/3)." }
+  ],
+  "lint": { "errors_introduced": 0 },
+  "typecheck": "PASS",
+  "tests": "3/3 passed",
+  "verdict_reason": "Backend enforced, frontend capped. Acceptance criteria trace to PASS.",
+  "reviewer": "reviewer",
+  "reviewed_at": "2026-08-20T04:17:00Z"
+}

work/artifacts/F-087/security.json

@@ -0,0 +1,15 @@
+{
+  "feature_id": "F-087",
+  "verdict": "APPROVED",
+  "checks": [
+    { "name": "No new attack surface", "result": "PASS", "notes": "Same inventory check used elsewhere; no new deps." },
+    { "name": "Error messages do not leak sensitive data", "result": "PASS", "notes": "Message exposes only variantId, requested, availableQuantity — all already known to the UI." },
+    { "name": "Auth chain unchanged", "result": "PASS", "notes": "Same cart routes; new error path goes through existing auth." }
+  ],
+  "sast": "PASS",
+  "dependency_review": "PASS",
+  "secret_scan": "PASS",
+  "verdict_reason": "Server-side validation strengthened; UI enforces the same cap.",
+  "reviewer": "security",
+  "reviewed_at": "2026-08-20T04:17:30Z"
+}

work/runtime-status.json

@@ -1,27 +1,13 @@
 {
-  "feature_id": "F-086",
+  "feature_id": "F-087",
   "stage": "build",
   "agent": "implementer",
-  "action": "adding expiration_date",
+  "action": "capping cart quantity to stock",
   "state": "running",
   "next_agent": "reviewer",
   "waiting_for": null,
-  "updated_at": "2026-08-20T04:11:27Z",
+  "updated_at": "2026-08-20T04:14:26Z",
   "timeline": [
-    {
-      "ts": "2026-08-19T19:08:01Z",
-      "agent": "architect",
-      "stage": "design",
-      "state": "running",
-      "message": "designing SSE log streaming"
-    },
-    {
-      "ts": "2026-08-19T19:09:08Z",
-      "agent": "implementer",
-      "stage": "build",
-      "state": "running",
-      "message": "implementing SSE log streaming"
-    },
     {
       "ts": "2026-08-19T20:57:51Z",
       "agent": "reviewer",
@@ -147,6 +133,20 @@
       "stage": "build",
       "state": "running",
       "message": "adding expiration_date"
+    },
+    {
+      "ts": "2026-08-20T04:13:40Z",
+      "agent": "leader",
+      "stage": "intake",
+      "state": "running",
+      "message": "starting F-087"
+    },
+    {
+      "ts": "2026-08-20T04:14:26Z",
+      "agent": "implementer",
+      "stage": "build",
+      "state": "running",
+      "message": "capping cart quantity to stock"
     }
   ],
   "last_updated": "2026-08-19T09:10:00Z",