@lexq/cli 0.1.52 → 0.1.54

package/AGENTS.md

@@ -129,8 +129,9 @@ Place this file in the project root. The IDE will auto-discover it.
 
 ### Claude Code
 
-Reads this file via the root `CLAUDE.md` pointer. No separate context file — this document and `skills/` are the whole
-guide.
+Reads this file through the root `CLAUDE.md`, which is a one-line import rather than a copy. There is no
+Claude-specific document to keep in sync. The CLI guide is this file plus `skills/`; `CONTEXT.md` covers platform
+architecture separately and ships alongside.
 
 ### Gemini CLI
 

package/dist/index.js

@@ -2359,6 +2359,7 @@ import "commander";
 import dedent9 from "dedent";
 
 // src/types/enums.ts
+var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
 var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
 var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
 var ProfileCacheState = ["HIT", "MISS"];
@@ -3405,7 +3406,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"),
@@ -3722,6 +3723,7 @@ import { z as z4 } from "zod";
 var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/mcp/tools/facts.ts
+var VALUE_TYPES = ValueType;
 function registerFactTools(server, callApi) {
   server.registerTool(
     "lexq_facts_list",
@@ -3748,7 +3750,7 @@ function registerFactTools(server, callApi) {
       inputSchema: {
         key: z4.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
         name: z4.string().describe("Display name"),
-        type: z4.enum(["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"]).describe("Value type"),
+        type: z4.enum(VALUE_TYPES).describe("Value type"),
         description: z4.string().optional().describe("Description"),
         isRequired: z4.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
         isPii: z4.boolean().default(false).describe(
@@ -3762,11 +3764,14 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      description: "Update a fact definition. Key and type cannot be changed. Only provided fields are updated. System facts only allow name, description, and PII changes.",
+      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Only the fields you send are changed. System facts accept name, description, and PII only.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID"),
         name: z4.string().optional().describe("Display name"),
         description: z4.string().optional().describe("Description"),
+        type: z4.enum(VALUE_TYPES).optional().describe(
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+        ),
         isRequired: z4.boolean().optional().describe("Required flag"),
         isPii: z4.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)")
       }
@@ -3777,7 +3782,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
-      description: "Delete a fact definition. System facts cannot be deleted.",
+      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Remove the references first.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID")
       }

package/dist/mcp/register.js

@@ -15,6 +15,7 @@ function registerStatusTools(server, callApi) {
 import { z } from "zod";
 
 // src/types/enums.ts
+var ValueType = ["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"];
 var ConflictResolutionMode = ["NONE", "EXCLUSIVE", "MAX_N"];
 var ConflictResolutionStrategy = ["HIGHEST_PRIORITY"];
 var FailureStatus = ["PENDING", "RESOLVED", "IGNORED"];
@@ -128,7 +129,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"),
@@ -514,6 +515,7 @@ import { z as z4 } from "zod";
 var FACT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
 
 // src/mcp/tools/facts.ts
+var VALUE_TYPES = ValueType;
 function registerFactTools(server, callApi) {
   server.registerTool(
     "lexq_facts_list",
@@ -540,7 +542,7 @@ function registerFactTools(server, callApi) {
       inputSchema: {
         key: z4.string().regex(FACT_KEY_PATTERN).describe("Variable key. Any casing; must start with a letter."),
         name: z4.string().describe("Display name"),
-        type: z4.enum(["STRING", "NUMBER", "BOOLEAN", "LIST_STRING", "LIST_NUMBER"]).describe("Value type"),
+        type: z4.enum(VALUE_TYPES).describe("Value type"),
         description: z4.string().optional().describe("Description"),
         isRequired: z4.boolean().default(false).describe("Whether this fact is required for rule evaluation"),
         isPii: z4.boolean().default(false).describe(
@@ -554,11 +556,14 @@ function registerFactTools(server, callApi) {
     "lexq_facts_update",
     {
       title: "Update Fact Definition",
-      description: "Update a fact definition. Key and type cannot be changed. Only provided fields are updated. System facts only allow name, description, and PII changes.",
+      description: "Update a fact definition. The key is immutable. The type can change only while no rule references the fact; if any does, the call fails with FD-007 and reports the count. Only the fields you send are changed. System facts accept name, description, and PII only.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID"),
         name: z4.string().optional().describe("Display name"),
         description: z4.string().optional().describe("Description"),
+        type: z4.enum(VALUE_TYPES).optional().describe(
+          "Value type. Omit to leave it unchanged. Changing it fails with FD-007 while any rule references the fact."
+        ),
         isRequired: z4.boolean().optional().describe("Required flag"),
         isPii: z4.boolean().optional().describe("PII flag \u2014 enables/disables masking (changeable even on system facts)")
       }
@@ -569,7 +574,7 @@ function registerFactTools(server, callApi) {
     "lexq_facts_delete",
     {
       title: "Delete Fact Definition",
-      description: "Delete a fact definition. System facts cannot be deleted.",
+      description: "Delete a fact definition. System facts cannot be deleted. Neither can a fact that any rule references: that call fails with FD-006 and reports the count. Remove the references first.",
       inputSchema: {
         factId: z4.string().uuid().describe("Fact definition ID")
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexq/cli",
-  "version": "0.1.52",
+  "version": "0.1.54",
   "description": "LexQ CLI — manage policies, simulate rules, and deploy from the terminal. Built for humans and AI agents.",
   "type": "module",
   "bin": {
@@ -31,6 +31,7 @@
     "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-shared/SKILL.md

@@ -141,7 +141,7 @@ Prefixes you will encounter through the CLI:
 | `A-`   | Auth                  | Invalid or missing API key                     |
 | `P-`   | Policy group/version  | Not found, wrong lifecycle state, already live |
 | `ACT-` | Action parameters     | Missing or invalid action parameter            |
-| `FD-`  | Fact definitions      | Duplicate key, system fact immutable           |
+| `FD-`  | Fact definitions      | Duplicate key, system fact immutable, fact still referenced by rules |
 | `AN-`  | Analytics             | Dry-run or simulation failure                  |
 | `FL-`  | Failure logs          | Log not found                                  |
 | `WH-`  | Webhook subscriptions | Invalid URL, delivery failure                  |

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: