Updated

Author: rezwana-karim

specs/002-harden-checkout-tenancy/plan.md

@@ -44,6 +44,8 @@ Gates from constitution:
 - Testing thresholds (80% services, 100% utils), E2E on critical paths — PLANNED
 - Accessibility (WCAG 2.1 AA, axe‑core) — PLANNED ENFORCEMENT
 
+Note: The project constitution contains an inconsistent high-level coverage statement elsewhere (references to 90%). For implementation and CI gates this plan follows the constitution's detailed thresholds: **80% services** and **100% utilities**. If a stricter global threshold is required (e.g., 90%), update the constitution/governance documents and CI policy accordingly.
+
 No violations detected at plan time. Re‑check after Phase 1 artifacts.
 
 ## Project Structure

specs/002-harden-checkout-tenancy/spec.md

@@ -113,13 +113,20 @@ As an admin, I receive consistent API responses and can export orders as CSV; sm
 - **FR-001**: Reject unauthenticated checkout attempts; require a valid signed-in session.
 - **FR-002**: Recalculate all line items, discounts, shipping, and taxes on the server; ignore client-submitted monetary values.
 - **FR-003**: Validate the provided payment intent/token with the payment processor prior to order creation; abort on validation failure.
+ - **FR-003**: Validate the provided payment intent/token with the payment processor prior to order creation; abort on validation failure.
+   - Clarification: Payment pre-validation MUST verify that the payment intent/authorization exists and that the expected amount and currency match server-side recalculated totals. The system SHOULD accept processor states such as "AUTHORIZED" or equivalent pre-authorized states for later capture; the implementation MUST document which states are merely validated vs which will be captured as part of order finalization.
+   - Idempotency & retries: Checkout submissions MUST include an idempotency key (client-provided or server-generated) to prevent duplicate captures. The payment adapter MUST implement safe retry/backoff semantics. In case of payment provider outages, the checkout flow MUST abort without creating an order or mutating inventory; a retryable error should be surfaced to the client and reconciliation attempted by background processes when appropriate.
 - **FR-004**: Execute order creation, order items, inventory decrement, discount usage mark, and payment record within a single atomic transaction.
 - **FR-005**: Resolve the active store from the request domain/subdomain and map it to a tenant identifier; return not-found if no mapping exists. When both a custom domain and subdomain exist, redirect subdomain traffic to the custom domain as the canonical host.
+ - **FR-005**: Resolve the active store from the request domain/subdomain and map it to a tenant identifier; return not-found if no mapping exists. When both a custom domain and subdomain exist, redirect subdomain traffic to the custom domain as the canonical host.
+   - Clarification: For storefront GET requests, the canonical redirect SHOULD use HTTP 301 (Permanent Redirect) and the response SHOULD include a `Link: <https://{primary-domain}{path}>; rel="canonical"` header to aid SEO. For non-GET requests (e.g., form POSTs), avoid automatic redirects that change method semantics; prefer returning an informative error so clients can re-submit to the canonical host if applicable.
 - **FR-006**: Eliminate hardcoded tenant identifiers from storefront components and services.
 - **FR-007**: Provide a newsletter subscription path that validates input, prevents duplicates per email+store, records explicit consent, supports rate limiting, and writes an audit entry; activate subscriptions immediately (single opt-in) with an audit trail.
 - **FR-008**: Standardize API responses: success `{ data, meta?, message? }`; error `{ error: { code, message, details? } }`.
 - **FR-009**: Enforce tenant scoping for all tenant-owned queries via a guaranteed filter on the tenant identifier.
 - **FR-010**: Align data fields where arrays vs delimited strings are inconsistent; add soft-delete fields where missing; validate forward data entry accordingly.
+ - **FR-010**: Align data fields where arrays vs delimited strings are inconsistent; add soft-delete fields where missing; validate forward data entry accordingly.
+   - Clarification: Candidate fields for normalization include, but are not limited to: `Product.images` (string[] vs CSV), `Product.tags` (string[] vs CSV), `Variant.attributes` (JSON vs CSV), and any CSV-encoded historical fields. The schema audit (T038) MUST produce an explicit per-field inventory artifact listing current type, recommended normalized type, migration approach, and backward-compatibility notes.
 - **FR-011**: Establish cache tag categories for key entities (e.g., products, categories, pages) and provide invalidation on create/update/delete actions.
 - **FR-012**: Produce a plan to adopt component-level caching in phases, initially disabled, with documented enablement steps and guardrails.
 - **FR-013**: Achieve and enforce test coverage thresholds (services ≥80%, utilities 100%) with tests for fraud scenarios, tenancy isolation, newsletter flows, and error mapping.
@@ -143,6 +150,7 @@ As an admin, I receive consistent API responses and can export orders as CSV; sm
 - **AuditLog**: Immutable record of significant actions (checkout created, subscription added) with correlation/request IDs.
 - **CacheTag**: Semantic identifiers used to manage cache invalidation across related views.
 - **RequestContext**: Correlation/request ID and store resolution used for logging and response headers.
+ - **RequestContext**: Correlation/request ID and store resolution used for logging and response headers. Implementation note: standardize the canonical store resolver filename to `src/lib/store/resolve-store.ts` across plan/tasks to avoid naming drift.
 
 ## Success Criteria *(mandatory)*
 

specs/002-harden-checkout-tenancy/tasks.md

@@ -57,12 +57,16 @@ Total tasks: 42 (grouped by phase and user story)
 - [ ] T036 [P] Final audit: run grep for hardcoded `storeId`, run coverage, Lighthouse, and axe and store artifacts in `specs/002-harden-checkout-tenancy/artifacts/`
 
 ## Remediation & Constitution Tasks (critical follow-ups)
-- [ ] T037 Add integration tests for every modified API route under `src/app/api/**/route.ts`; ensure each modified route has a corresponding integration test in `tests/integration/` and fail pre-merge when missing (map to FR-013, constitution MUST)
-- [ ] T038 Schema audit: scan `prisma/schema.prisma` and codebase for CSV/string[] inconsistencies (images, tags, other arrays); create per-field migration tasks and tests under `tests/integration/migrations/`
+- [ ] T037 Add integration tests for every API route under `src/app/api/**/route.ts`; ensure each route (not only modified ones) has a corresponding integration test in `tests/integration/`. Add a CI check that fails pre-merge if any API route lacks an integration test. (maps to FR-013 and constitution MUST)
+- [ ] T038 Schema audit: scan `prisma/schema.prisma` and codebase for CSV/string[] inconsistencies (images, tags, attributes, variants, metadata arrays); create per-field migration tasks and tests under `tests/integration/migrations/` with an explicit inventory output artifact.
 - [ ] T039 Add k6 load test scripts for checkout and orders export and add Lighthouse CI job to feature CI pipeline; document thresholds and integrate into `.github/workflows/` (map to constitution performance requirements)
 - [ ] T040 Background job infra validation: confirm existing job processing infra (worker/queue); if missing, add lightweight dev stub and update `src/services/export-service.ts` to support stub in dev/test
 - [ ] T041 Payment pre-validation robustness: add idempotency key handling, retry/backoff policy, and tests for provider outages (update `src/services/payments/intent-validator.ts` and tests)
-- [ ] T042 REST audit: scan `src/app/api/**/route.ts` for REST violations (PUT/PATCH misuse, stray `success` flags) and create remediation subtasks to fix each violating endpoint
+- [ ] T042 REST audit: scan `src/app/api/**/route.ts` for REST violations (PUT/PATCH misuse, stray `success` flags). Produce per-endpoint remediation tasks with deadlines and CI gating to ensure fixes are applied before merge.
+
+## Additional Tasks (Governance & CI)
+- [ ] T043 Percy + Visual Regression: Integrate Percy visual regression for critical pages and UI components (dashboard, checkout, product list). Add Percy job to feature CI and create snapshot baselines. Map to constitution visual regression requirements.
+- [ ] T044 CI k6 & Lighthouse gating: Add CI jobs to run k6 (load) and Lighthouse CI with defined thresholds; fail PRs or block merge if thresholds are not met for PRs touching critical paths.
 
 ---
 
@@ -85,8 +89,8 @@ Total tasks: 42 (grouped by phase and user story)
 Path to generated tasks.md: `specs/002-harden-checkout-tenancy/tasks.md`
 
 Summary:
-- Total tasks: 36
-- Tasks per story: US1:6, US2:5, US3:5, US4:4, Foundational:6, Setup:3, Final/Polish:7
+- Total tasks: 42
+- Tasks per story (approx): US1:6, US2:6, US3:5, US4:5, Foundational:6, Setup:3, Final/Polish:7
 - Parallel opportunities: Foundational helpers (T004–T009) and docs/tests (T033–T036)
 - Suggested MVP: US1 minimal slice (T010, T011, T013)
 
@@ -155,8 +159,8 @@ This plan breaks the specification into implementable tasks with owners, concret
   - Schema: add `StoreDomain` model
     - `id`, `storeId`, `domain` (unique), `isPrimary` (canonical), timestamps
   - Files: `prisma/schema.prisma` (model + `@@unique([domain])`), migration; seed example
-  - Files: `src/lib/store-resolver.ts` (new): parse host, resolve `storeId` by domain OR `slug.subdomain`
-  - Proxy: add canonical redirect: if request for subdomain and primary custom domain exists → 308 redirect
+  - Files: `src/lib/store/resolve-store.ts` (new): parse host, resolve `storeId` by domain OR `slug.subdomain`
+  - Proxy: add canonical redirect: if request for subdomain and primary custom domain exists → 301 Permanent Redirect; include a `Link: <https://{primary-domain}{path}>; rel="canonical"` header for SEO
   - Tests: `tests/unit/store-resolver.test.ts`, `tests/integration/canonical-redirect.test.ts`
 
 - T2.2 Remove hardcoded store IDs and enforce tenant scoping (FR-006, FR-009)