From d37b682ebbef87426e458578d9fdb67d7dfb5f2b Mon Sep 17 00:00:00 2001
From: Xavier <1859710+xavierjohn@users.noreply.github.com>
Date: Sat, 4 Jul 2026 17:00:58 -0700
Subject: [PATCH 1/2] Clarify Order Management spec audience is
 internal/staff-facing

Add an explicit Audience note to the Domain Overview: the system's users are staff actors (sales representatives, warehouse managers, administrators) acting on behalf of customers, so an order's customerId is supplied in the request while CreatedByActorId records the staff member who created it. Notes that a customer self-service design would instead derive the customer from the authenticated actor. Resolves the ambiguity between the 'customers place orders' narrative and the staff role model.
---
 specs/order-management.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/specs/order-management.md b/specs/order-management.md
index fd7a649..a0b120b 100644
--- a/specs/order-management.md
+++ b/specs/order-management.md
@@ -8,6 +8,8 @@ A company sells products to customers. Customers place orders, each order contai
 
 The system uses role-based access control. Sales representatives create customers and orders. Warehouse managers approve and ship orders. Administrators have full access.
 
+**Audience — internal, staff-facing.** The system's users are these staff actors (sales representatives, warehouse managers, administrators), *not* the customers themselves. A sales rep places an order **on behalf of** a customer: the order's customer is supplied in the request (the rep selects which customer), while `CreatedByActorId` records the staff member who created it. Consequently, holding `orders:create` authorizes creating an order for **any existing** customer — subject only to the customer-exists check, with deliberately no per-customer ownership check on creation. (A customer self-service system would instead derive the order's customer from the authenticated actor rather than trusting a request field.)
+
 ## 2. Ubiquitous Language
 
 | Term | Definition |

From ac1819c034774f39964b03850522882cc778511b Mon Sep 17 00:00:00 2001
From: Xavier <1859710+xavierjohn@users.noreply.github.com>
Date: Sat, 4 Jul 2026 17:33:03 -0700
Subject: [PATCH 2/2] Reconcile business 'customers place orders' phrasing with
 the staff-operated API in the Audience note; split into shorter sentences for
 clarity

---
 specs/order-management.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specs/order-management.md b/specs/order-management.md
index a0b120b..03152fc 100644
--- a/specs/order-management.md
+++ b/specs/order-management.md
@@ -8,7 +8,7 @@ A company sells products to customers. Customers place orders, each order contai
 
 The system uses role-based access control. Sales representatives create customers and orders. Warehouse managers approve and ship orders. Administrators have full access.
 
-**Audience — internal, staff-facing.** The system's users are these staff actors (sales representatives, warehouse managers, administrators), *not* the customers themselves. A sales rep places an order **on behalf of** a customer: the order's customer is supplied in the request (the rep selects which customer), while `CreatedByActorId` records the staff member who created it. Consequently, holding `orders:create` authorizes creating an order for **any existing** customer — subject only to the customer-exists check, with deliberately no per-customer ownership check on creation. (A customer self-service system would instead derive the order's customer from the authenticated actor rather than trusting a request field.)
+**Audience — internal, staff-facing.** The system's users are the staff actors above (sales representatives, warehouse managers, administrators), *not* the customers themselves. Phrases like "customers place orders" describe the **business domain**; the **API is operated by staff on customers' behalf**. A sales rep places an order for a customer: the order's customer is supplied in the request (the rep selects which customer), while `CreatedByActorId` records the staff member who created it. Holding `orders:create` therefore authorizes creating an order for **any existing** customer. The only check is that the customer exists; there is deliberately no per-customer ownership check on creation. (A customer self-service system would instead derive the order's customer from the authenticated actor rather than trusting a request field.)
 
 ## 2. Ubiquitous Language