docs(audit): align documentation with post-remediation backend reality

- Update data model enums to match backend models
- Update API reference auth requirements
- Add dispute module references and warning blocks
- Add 2026-05-24 audit remediation callout to Overview
- Generate task breakdowns and audit artifacts
- Add doc alignment report (.taskmaster/reports/)

04 - Flows/Dispute Flow.md

@@ -15,7 +15,9 @@ When something goes wrong (item not delivered, wrong item, fraud), either party
 - **Seller** — party against whom the dispute is raised (or in rarer cases, initiator).
 - **Admin / Mediator** — assigned to investigate.
 - **Frontend** — buyer/seller "Report issue" buttons in the request detail view; admin dispute dashboard.
-- **Backend** — `DisputeService` (`backend/src/services/dispute/DisputeService.ts`), `DisputeController` (`backend/src/controllers/disputeController.ts`), routes at `backend/src/routes/disputeRoutes.ts`.
+- **Backend** — `DisputeService` (`backend/src/services/dispute/DisputeService.ts` *(planned)*), `DisputeController` (`backend/src/controllers/disputeController.ts` *(planned)*), routes at `backend/src/routes/disputeRoutes.ts` *(planned)*.
+  > [!warning] Not implemented
+  > None of these files exist as of 2026-05-24. The dispute module is planned but not yet built.
 - **MongoDB** — `disputes`, `chats`, `purchaserequests`, `payments`.
 - **Socket.IO** — `new-notification`, `new-message`, `dispute-updated` (planned).
 
@@ -38,7 +40,7 @@ stateDiagram-v2
     closed --> [*]
 ```
 
-Resolution actions (from `Dispute.resolution.action` enum, see `Dispute.ts`): `refund`, `partial`, `release`, `reject` (the wording differs slightly in the model — verify with `backend/src/models/Dispute.ts`).
+Resolution actions (from `Dispute.resolution.action` enum, see `Dispute.ts` *(intended design)*): `refund`, `partial`, `release`, `reject`.
 
 ## Step-by-step narrative
 
@@ -193,9 +195,12 @@ All require `authenticateToken` (router-level middleware).
 
 ## Source files
 
-- Backend: `backend/src/services/dispute/DisputeService.ts`
-- Backend: `backend/src/controllers/disputeController.ts`
-- Backend: `backend/src/routes/disputeRoutes.ts`
-- Backend: `backend/src/models/Dispute.ts`
+> [!warning] Not implemented
+> None of the backend files below exist as of 2026-05-24. The dispute module is planned but not yet built.
+
+- Backend: `backend/src/services/dispute/DisputeService.ts` *(planned)*
+- Backend: `backend/src/controllers/disputeController.ts` *(planned)*
+- Backend: `backend/src/routes/disputeRoutes.ts` *(planned)*
+- Backend: `backend/src/models/Dispute.ts` *(planned)*
 - Frontend: `frontend/src/sections/request/components/report-problem-to-admin.tsx`
 - Frontend: admin dispute dashboard under `frontend/src/sections/admin/` (subject to organisation)

04 - Flows/Escrow Flow.md

@@ -19,7 +19,7 @@ The escrow is not a separate smart contract — it is a **state machine on the `
 
 ## Escrow state machine (`Payment.escrowState`)
 
-Enum from `Payment.ts:112-115`: `funded | releasable | released | refunded | releasing | failed`.
+Enum from `Payment.ts:112-115`: `funded | releasable | released | refunded | releasing | failed | cancelled | partial`.
 
 ```mermaid
 stateDiagram-v2
@@ -33,9 +33,12 @@ stateDiagram-v2
     Releasing --> Failed: payout tx reverted\nescrowState="failed"
     Funded --> Refunded: dispute resolution = refund\nescrowState="refunded"
     Funded --> Refunded: order cancelled\npre-shipment
+    Pending --> Cancelled: webhook EXPIRED/CANCELLED
+escrowState="cancelled"
     Failed --> Releasing: admin retries
     Released --> [*]
     Refunded --> [*]
+    Cancelled --> [*]
 ```
 
 `Payment.status` mirrors a coarser business state:

04 - Flows/Payment Flow - DePay & Web3.md

@@ -35,7 +35,7 @@ Alternative pay-in path: instead of routing through [[Payment Flow - SHKeeper]],
 
 ### Phase 2 — Create intent on backend
 
-4. Frontend POSTs `POST /api/payment/decentralized/create` with `{ purchaseRequestId, sellerOfferId, amount, fromAddress: wallet.address, token: 'USDT', network: 'bsc' }`. The backend records a `Payment` with `provider: 'other'` (or `'decentralized'` depending on enum extension), `direction: 'in'`, `status: 'pending'`, `blockchain.{network, token, sender, receiver: ESCROW_WALLET_ADDRESS}`.
+4. Frontend POSTs `POST /api/payment/decentralized/save` with `{ purchaseRequestId, sellerOfferId, amount, fromAddress: wallet.address, token: 'USDT', network: 'bsc' }`. The backend records a `Payment` with `provider: 'other'` (or `'decentralized'` depending on enum extension), `direction: 'in'`, `status: 'pending'`, `blockchain.{network, token, sender, receiver: ESCROW_WALLET_ADDRESS}`. **Auth:** Bearer JWT required.
 5. Response includes the **escrow wallet address** and the exact token amount (in decimals — for USDT-BEP20 that's 18 decimals; the helper `convertPaymentAmountForShkeeper` is shared from `currencyUtils.ts`).
 
 ### Phase 3 — Token approval (ERC-20 / BEP-20)
@@ -52,7 +52,7 @@ Alternative pay-in path: instead of routing through [[Payment Flow - SHKeeper]],
 
 ### Phase 5 — Backend verification
 
-11. Frontend POSTs `POST /api/payment/decentralized/verify` with `{ paymentId, transactionHash }`.
+11. Frontend POSTs `POST /api/payment/decentralized/verify/:paymentId` with `{ transactionHash }`. **Auth:** Bearer JWT required (owner or admin).
 12. Backend `BSCTransactionVerifier.verifyTransaction(txHash)` (`decentralizedPaymentService.ts`):
     - JSON-RPC `eth_getTransactionReceipt` against `bsc-dataseed.binance.org`.
     - Confirms `receipt.status === '0x1'` (success).