@lexq/cli 0.1.51 → 0.1.53

package/dist/index.js

@@ -3405,7 +3405,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_start",
     {
       title: "Start A/B Test",
-      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate.",
+      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate. The split is computed from context.trafficKey on each execution request; requests that omit it never reach the challenger and the test stays at 0%.",
       inputSchema: {
         groupId: z.string().uuid().describe("Policy group ID"),
         testVersionId: z.string().uuid().describe("Challenger version ID to test"),

package/dist/mcp/register.js

@@ -128,7 +128,7 @@ function registerGroupTools(server, callApi) {
     "lexq_ab_test_start",
     {
       title: "Start A/B Test",
-      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate.",
+      description: "Start an A/B test on a policy group. Requires a challenger version ID and traffic rate. The split is computed from context.trafficKey on each execution request; requests that omit it never reach the challenger and the test stays at 0%.",
       inputSchema: {
         groupId: z.string().uuid().describe("Policy group ID"),
         testVersionId: z.string().uuid().describe("Challenger version ID to test"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -30,6 +30,8 @@
     "enums": "node scripts/gen-enums.mjs",
     "enums:check": "node scripts/gen-enums.mjs --check",
     "constants:check": "node scripts/check-constants.mjs",
+    "surface:check": "node scripts/check-public-surface.mjs",
+    "ab-key:check": "node scripts/check-ab-key.mjs",
     "start": "node dist/index.js",
     "test:decimals": "pnpm build && node tests/exact-decimals.mjs",
     "test:fact-key": "node tests/fact-key.mjs",

package/skills/lexq-groups/SKILL.md

@@ -159,6 +159,33 @@ lexq groups create --json '{
 
 Split traffic between the current live version and a test version.
 
+### Traffic Identity Key
+
+**Every execution request has to carry `context.trafficKey`.** That value is what the split is
+computed from: the server hashes it together with the group ID and assigns the request to a
+bucket, so the same key value always reaches the same version for that group.
+
+Send it in `context`, not in `facts`. Routing never reads `facts`.
+
+```json
+{
+  "facts": { "paymentAmount": 150000, "customerTier": "VIP" },
+  "context": { "trafficKey": "customer-8f3a21" }
+}
+```
+
+If the key is missing or empty, no request is ever assigned to the test version. The test still
+reports as running and execution logs keep accumulating, so **the failure does not surface in the
+response** — only a server-side warning records it. This is the most common reason a test sits
+at 0%.
+
+Pick a value that is stable per experiment unit (a customer ID, a merchant ID, a session ID) and
+opaque — the whole `context` object is stored on the execution ledger, so send a hash or a
+surrogate key rather than an email address. A value that changes every request, such as a request
+ID, scatters one user across both versions and destroys the comparison.
+
+Batch calls read `sharedContext.trafficKey` instead, and the whole batch runs on one version.
+
 ### Start A/B Test
 
 ```bash
@@ -191,11 +218,12 @@ This reverts all traffic to the main version. The test version remains ACTIVE bu
 ```
 1. Create two versions (v1 live, v2 DRAFT with changes)
 2. Publish v2: lexq deploy publish --group-id <gid> --version-id <v2id>
-3. Start A/B: lexq groups ab-test start --group-id <gid> --version-id <v2id> --traffic-rate 10
-4. Monitor: lexq history stats  (compare metrics)
-5. Adjust traffic gradually: 10% → 30% → 50%
-6. Promote winner: lexq deploy live --group-id <gid> --version-id <v2id>
-7. Stop test: lexq groups ab-test stop --group-id <gid> --force
+3. Confirm your execution requests send context.trafficKey
+4. Start A/B: lexq groups ab-test start --group-id <gid> --version-id <v2id> --traffic-rate 10
+5. Monitor: lexq history stats  (compare metrics)
+6. Adjust traffic gradually: 10% → 30% → 50%
+7. Promote winner: lexq deploy live --group-id <gid> --version-id <v2id>
+8. Stop test: lexq groups ab-test stop --group-id <gid> --force
 ```
 
 ## Common Patterns

package/skills/lexq-recipes/SKILL.md

@@ -190,6 +190,7 @@ lexq analytics dry-run --version-id <v2id> --debug --json '{
 lexq deploy publish --group-id <gid> --version-id <v2id> --memo "15% discount test"
 
 # 5. Start A/B test at 10% traffic
+#    Your execution requests must carry context.trafficKey, or the test stays at 0%.
 lexq groups ab-test start --group-id <gid> --version-id <v2id> --traffic-rate 10
 
 # 6. Monitor (check execution stats periodically)

package/skills/lexq-simulation/SKILL.md

@@ -60,6 +60,11 @@ Response includes:
 
 **Always run this before dry-run.** Copy `exampleRequest.facts` as your starting template and fill in real values.
 
+`exampleRequest.context` comes back empty, and it stays empty even when the group has an A/B test
+running. Live execution requests against such a group also need `context.trafficKey` or the test
+version receives no traffic — see the A/B testing section of the groups skill. Dry-run itself is
+unaffected: it always evaluates the version you name, so routing never applies here.
+
 ## 2. Dry Run (Single Input)
 
 Test a single set of facts against a version: