@lexq/cli 0.1.40 → 0.1.42

package/skills/lexq-execution/SKILL.md

@@ -5,7 +5,7 @@
 ## Overview
 
 Once policies are deployed, the engine evaluates incoming facts against live rules. This skill covers **observing**
-production behavior: execution history, statistics, failure logs, and integrations.
+production behavior: execution history, statistics, failure logs, and deployment state.
 
 ## 1. Execution History
 
@@ -28,12 +28,16 @@ Filter options:
 
 ### Execution Statuses
 
-| Status     | Meaning                                        |
-|------------|------------------------------------------------|
-| `SUCCESS`  | At least one rule matched and actions executed |
-| `NO_MATCH` | No rules matched the input facts               |
-| `ERROR`    | Engine error during evaluation                 |
-| `TIMEOUT`  | Execution exceeded time limit                  |
+| Status     | Meaning                                                                                       |
+|------------|-----------------------------------------------------------------------------------------------|
+| `SUCCESS`  | At least one rule matched and actions executed                                                |
+| `NO_MATCH` | No rules matched — or the version was not evaluated at all (e.g. outside its effective dates) |
+| `ERROR`    | Engine error during evaluation                                                                |
+| `TIMEOUT`  | Execution exceeded time limit                                                                 |
+
+A version outside its effective date range is filtered before evaluation, so no per-rule trace is produced for it. If a
+rule you expect never appears in `decisionTraces`, check the version's `effectiveFrom` / `effectiveTo` with
+`lexq versions get`.
 
 ### Get Execution Detail
 
@@ -70,7 +74,16 @@ Use stats to monitor:
 
 ## 2. Failure Logs
 
-System failure logs capture errors from background tasks (batch jobs, webhook calls, scheduled operations).
+Failure logs are a dead-letter record for background tasks that failed after the request returned.
+Two task types exist:
+
+| Task type              | What failed                                                      |
+|------------------------|------------------------------------------------------------------|
+| `PLATFORM_WEBHOOK`     | A platform event webhook delivery (`lexq webhook-subscriptions`) |
+| `SCHEDULED_DEPLOYMENT` | A scheduled deployment that could not be armed or executed       |
+
+Policy execution failures do **not** land here — they surface in execution history with
+status `ERROR`.
 
 ### List Failure Logs
 
@@ -80,14 +93,13 @@ lexq logs list --page 0 --size 20
 
 Filter options:
 
-| Flag                  | Description                             | Values                                                               |
-|-----------------------|-----------------------------------------|----------------------------------------------------------------------|
-| `--category <cat>`    | Task category                           | `INTEGRATION`, `INTERNAL`                                            |
-| `--task-type <type>`  | Task type                               | `COUPON_ISSUE`, `POINT_EARN`, `NOTIFICATION_SEND`, `WEBHOOK_EXECUTE` |
-| `--status <status>`   | Log status                              | `PENDING`, `RESOLVED`, `IGNORED`                                     |
-| `--keyword <kw>`      | Search in refId, refSubId, errorMessage | any string                                                           |
-| `--start-date <date>` | Start date (ISO)                        | `2025-01-01`                                                         |
-| `--end-date <date>`   | End date (ISO)                          | `2025-01-31`                                                         |
+| Flag                  | Description                             | Values                                     |
+|-----------------------|-----------------------------------------|--------------------------------------------|
+| `--task-type <type>`  | Task type                               | `PLATFORM_WEBHOOK`, `SCHEDULED_DEPLOYMENT` |
+| `--status <status>`   | Log status                              | `PENDING`, `RESOLVED`, `IGNORED`           |
+| `--keyword <kw>`      | Search in refId, refSubId, errorMessage | any string                                 |
+| `--start-date <date>` | Start date (ISO)                        | `2025-01-01`                               |
+| `--end-date <date>`   | End date (ISO)                          | `2025-01-31`                               |
 
 ### Get Failure Log Detail
 
@@ -95,102 +107,142 @@ Filter options:
 lexq logs get --id <logId>
 ```
 
-### Retry Failed Log
+Includes the original payload and error message. Use it to diagnose before marking the log.
 
-```bash
-lexq logs action --id <logId> --action RETRY
-```
+### Mark a Log
 
-### Resolve (Mark as Handled)
+There is no retry action — the engine does not re-execute a failed task on request. Fix the cause
+at the source (webhook endpoint, version state), then mark the log.
 
 ```bash
-lexq logs action --id <logId> --action RESOLVE
+lexq logs action --id <logId> --action RESOLVE   # cause was fixed
+lexq logs action --id <logId> --action IGNORE    # does not need fixing
 ```
 
-### Ignore (Skip Retries)
-
-```bash
-lexq logs action --id <logId> --action IGNORE
-```
+Both remove the log from `PENDING`; they differ only in recorded intent.
 
 ### Bulk Operations
 
 ```bash
-lexq logs bulk-action --ids "id1,id2,id3" --action RETRY
 lexq logs bulk-action --ids "id1,id2,id3" --action RESOLVE
+lexq logs bulk-action --ids "id4,id5" --action IGNORE
 ```
 
-## 3. Integrations
+## 3. Deployment Monitoring
 
-Integrations connect LexQ actions to external systems (webhooks, CRM, notification services).
+### Deployment Overview
 
-### List Integrations
+See all groups' deployment status at a glance:
 
 ```bash
-lexq integrations list --page 0 --size 10
+lexq deploy overview
 ```
 
-### Get Integration
+Returns an array with each group's current version, last deployment type, and deployer.
+
+### Deployment History
 
 ```bash
-lexq integrations get --id <integrationId>
+lexq deploy history --page 0 --size 20
+lexq deploy history --group-id <gid>
+lexq deploy history --types DEPLOY,ROLLBACK --start-date 2025-01-01
 ```
 
-### Get Config Spec
-
-Shows available integration types and their required configuration fields:
+### Deployment Detail
 
 ```bash
-lexq integrations config-spec
+lexq deploy detail --id <deploymentId>
 ```
 
-### Save (Create or Update)
+Includes snapshot hash verification (`hashValid` field) to detect if a version was modified after deployment.
+
+### Scheduled Deployment
+
+A version with a future `effectiveFrom` can be armed to deploy itself at that time.
 
 ```bash
-lexq integrations save --json '{
-  "type": "WEBHOOK",
-  "name": "Order Webhook",
-  "baseUrl": "https://api.example.com/webhook",
-  "isActive": true
-}'
+# Arm — the version must be ACTIVE (published) with a future effective start
+lexq deploy schedule --group-id <gid> --version-id <vid> --memo "Q4 pricing"
+
+# List all schedules (PENDING, EXECUTED, CANCELED, FAILED)
+lexq deploy schedules --format table
+
+# Cancel the pending schedule (the version itself is untouched)
+lexq deploy unschedule --group-id <gid> --force
 ```
 
-Integration types: `COUPON`, `POINT`, `NOTIFICATION`, `CRM`, `MESSENGER`, `WEBHOOK`
+One pending schedule per group. The scheduler deploys within one tick (≤60s) of the effective
+start. A manual deploy, rollback, undeploy, A/B test start, or group archive **cancels** the
+pending schedule — the cancellation reason is recorded in the schedule ledger.
+
+The snapshot hash is sealed at scheduling time. If the version changes before the effective start,
+the scheduled deploy fails with `HASH_MISMATCH` rather than deploying something unexpected.
 
-### Delete Integration
+## 4. Decision Provenance
+
+Every execution is sealed with a `traceId`. Provenance answers "why did this decision happen"
+deterministically — which rules fired, which lost, and to what.
 
 ```bash
-lexq integrations delete --id <integrationId>
-lexq integrations delete --id <integrationId> --force
+lexq provenance get --trace-id <traceId>
 ```
 
-## 4. Deployment Monitoring
+Returns the decision, per-rule reason codes (`FINAL_WINNER`, `CONDITION_MISMATCH`, `MUTEX_PRIORITY_LOST`,
+`GROUP_LIMIT_REACHED`, …), and the sealed version snapshot hash.
 
-### Deployment Overview
+A rule that lost conflict resolution has status `BLOCKED` — unrelated to the `BLOCK` action, which writes the
+`is_blocked` fact while its own rule stays `SELECTED`.
 
-See all groups' deployment status at a glance:
+### PII Reveal Audit
+
+Facts marked `isPii` are masked on every read surface. Unmasking is possible only in the console
+and every reveal is recorded.
 
 ```bash
-lexq deploy overview
+lexq provenance reveal-audits
 ```
 
-Returns an array with each group's current version, last deployment type, and deployer.
+Returns who revealed which fact of which trace, and when.
 
-### Deployment History
+## 5. Decision Replay
+
+Re-evaluate past executions against a candidate version to see what would have changed.
 
 ```bash
-lexq deploy history --page 0 --size 20
-lexq deploy history --group-id <gid>
-lexq deploy history --types DEPLOY,ROLLBACK --start-date 2025-01-01
+# Single decision
+lexq replay decision --trace-id <traceId> --version-id <candidateVid>
+
+# A date window, as an async job
+lexq replay start --version-id <candidateVid> --from 2025-01-01 --to 2025-01-31
+# --max-records caps the sample (hard cap 50k)
+lexq replay get --id <jobId>
+lexq replay list
+lexq replay cancel --id <jobId>
 ```
 
-### Deployment Detail
+Replay reports whether the outcome is `DETERMINISTIC` or `REPLAY_MAY_DIFFER` — the latter when the
+original execution depended on values the replay cannot reproduce.
+
+## 6. Latency Profile
+
+Per-rule latency distribution for a policy group.
 
 ```bash
-lexq deploy detail --id <deploymentId>
+lexq profile <groupId>
+
+# Single-rule detail — distributions + 60s window series
+lexq profile <groupId> --rule <ruleId>
+
+# Defaults: live version, last 24h, cache HIT
+lexq profile <groupId> --version <vid> --cache MISS \
+  --from 2026-07-01T00:00:00Z --to 2026-08-01T00:00:00Z
 ```
 
-Includes snapshot hash verification (`hashValid` field) to detect if a version was modified after deployment.
+`--from` / `--to` are ISO-8601 **instants** here (`2026-07-01T00:00:00Z`), unlike `replay start`
+which takes `yyyy-MM-dd` dates.
+
+`p50` / `p95` / `p99` are `null` when the sample is under 100 — the engine reports insufficient
+data rather than inventing a number. `n` is always present.
 
 ## Agent Monitoring Workflow
 
@@ -201,13 +253,16 @@ lexq history stats
 # 2. If failure rate is high, investigate
 lexq history list --status ERROR --page 0 --size 10
 
-# 3. Check for system failures
+# 3. For a specific bad decision, get the deterministic why
+lexq provenance get --trace-id <traceId>
+
+# 4. Check for system failures
 lexq logs list --status PENDING --page 0 --size 10
 
-# 4. Retry or resolve failures
-lexq logs action --id <logId> --action RETRY
+# 5. Inspect and mark
+lexq logs get --id <logId>
 lexq logs action --id <logId> --action RESOLVE
 
-# 5. Verify deployment integrity
+# 6. Verify deployment integrity
 lexq deploy overview
 ```

package/skills/lexq-groups/SKILL.md

@@ -4,19 +4,21 @@
 
 ## Overview
 
-A **Policy Group** is the top-level container. It holds versions (each containing rules), manages deployment state, and controls conflict resolution when multiple groups interact.
+A **Policy Group** is the top-level container. It holds versions (each containing rules), manages deployment state, and
+controls conflict resolution when multiple groups interact.
 
 ## Status Lifecycle
 
-```
-ACTIVE ──→ DISABLED (emergency stop, re-enable anytime)
-  │              │
-  └──→ ARCHIVED ←┘  (permanent, cannot be restored)
-```
+| From       | To         | Reversible                        |
+|------------|------------|-----------------------------------|
+| `ACTIVE`   | `DISABLED` | yes — set status back to `ACTIVE` |
+| `DISABLED` | `ACTIVE`   | —                                 |
+| `ACTIVE`   | `ARCHIVED` | **no**                            |
+| `DISABLED` | `ARCHIVED` | **no**                            |
 
-- **ACTIVE**: Normal operation. Executions are processed.
-- **DISABLED**: All executions are blocked. Use for emergency stop. Can re-enable by updating status back to ACTIVE.
-- **ARCHIVED**: Permanently removed from execution. Cannot be undone.
+- **ACTIVE** — executions are processed.
+- **DISABLED** — all executions are blocked. Use for emergency stop.
+- **ARCHIVED** — removed from execution. Reached only through `lexq groups delete`, not by setting `status` directly.
 
 ## CRUD Commands
 
@@ -40,36 +42,49 @@ Returns full detail including `activationMode`, `activationStrategy`, `execution
 lexq groups create --json '{
   "name": "discount-policy",
   "description": "VIP discount rules",
-  "priority": 0,
   "activationMode": "NONE",
-  "activationStrategy": "FIRST_MATCH",
+  "activationStrategy": "HIGHEST_PRIORITY",
   "status": "ACTIVE"
 }'
 ```
 
-**Required fields:** `name`, `priority`
+**Required field:** `name`
+
+`priority` is assigned by the server, not by you — new groups are appended last. Change the order
+with `lexq groups reorder`. Priorities are 1-based (1 is highest).
 
 **Optional fields with defaults:**
 
-| Field | Default | Description |
-|---|---|---|
-| `activationMode` | `NONE` | Conflict resolution mode |
-| `activationStrategy` | `FIRST_MATCH` | Strategy within the mode |
-| `executionLimit` | `null` | Max rules that can fire |
-| `activationGroup` | `null` | Logical group for cross-group conflict resolution |
-| `status` | `ACTIVE` | Initial status |
+| Field                | Default            | Description                                        |
+|----------------------|--------------------|----------------------------------------------------|
+| `activationMode`     | `NONE`             | Conflict resolution mode                           |
+| `activationStrategy` | `HIGHEST_PRIORITY` | Strategy within the mode. Currently the only value |
+| `executionLimit`     | `null`             | Max rules that can fire                            |
+| `activationGroup`    | `null`             | Logical group for cross-group conflict resolution  |
+| `status`             | `ACTIVE`           | Initial status                                     |
 
 ### Update Group
 
 ```bash
 lexq groups update --id <groupId> --json '{
   "name": "updated-discount-policy",
-  "priority": 1
+  "description": "Updated description"
 }'
 ```
 
 Only include fields you want to change. Omitted fields are not modified.
 
+### Reorder Groups
+
+Priorities are **tenant-wide**, not per activation group. Pass group IDs in desired order; the
+server assigns 1, 2, 3, … (1…N continuous):
+
+```bash
+lexq groups reorder --group-ids "<gid_A>,<gid_B>,<gid_C>"
+```
+
+`activationGroup` is not affected — reorder changes priority only.
+
 ### Delete Group
 
 ```bash
@@ -78,27 +93,45 @@ lexq groups delete --id <groupId>
 lexq groups delete --id <groupId> --force
 ```
 
-**Warning:** Deleting a group cascades — all versions, rules, and deployment history are removed.
+**`delete` archives — it does not erase.** The group becomes `ARCHIVED` and stops executing;
+versions, rules, and history are retained for audit. Deleting an already-archived group is a
+no-op.
+
+Two conditions block it:
+
+| Condition              | What to do first                                    |
+|------------------------|-----------------------------------------------------|
+| The group is deployed  | `lexq deploy undeploy --group-id <gid>`             |
+| An A/B test is running | `lexq groups ab-test stop --group-id <gid> --force` |
+
+Archiving cancels any pending scheduled deployment and closes the priority gap — remaining groups
+are renumbered 1…N.
 
 ## Conflict Resolution
 
 ### Activation Mode (across groups in the same `activationGroup`)
 
-| Mode | Behavior |
-|---|---|
-| `NONE` | All matching rules fire. No conflict resolution. |
-| `EXCLUSIVE` | Only one group wins within the activation group. |
-| `MAX_N` | Up to `executionLimit` groups can fire. |
+| Mode        | Behavior                                                           |
+|-------------|--------------------------------------------------------------------|
+| `NONE`      | All matching rules fire. No conflict resolution.                   |
+| `EXCLUSIVE` | Only one group wins within the activation group.                   |
+| `MAX_N`     | Up to `executionLimit` groups fire. Omit it and the server sets 2. |
 
 ### Activation Strategy
 
-| Strategy | Behavior |
-|---|---|
-| `FIRST_MATCH` | First matching group by priority wins. |
-| `HIGHEST_PRIORITY` | Lowest priority number wins (0 = highest). |
-| `MAX_BENEFIT` | Group producing the largest action value wins. |
+| Strategy           | Behavior                                                                 |
+|--------------------|--------------------------------------------------------------------------|
+| `HIGHEST_PRIORITY` | Lowest priority number wins (1 is highest). Currently the only strategy. |
 
-**Constraint:** All groups sharing the same `activationGroup` **must** use identical `activationMode` and `activationStrategy`. The API rejects mismatches with `ACTIVATION_CONFIG_MISMATCH`.
+**Constraint:** All groups sharing the same `activationGroup` **must** use identical
+`activationMode` and `activationStrategy`. The API rejects mismatches with a `P-` error.
+
+Groups are selected by the order you set, not by comparing action values. `FIRST_MATCH` and
+`MAX_BENEFIT` were removed on 2026-08-01 — the former resolved identically to
+`HIGHEST_PRIORITY` (candidates are evaluated in priority order, so "first match" *is* "lowest
+priority number"), and the latter compared post-action values as scores, which made a 20%
+discount lose to a 10% discount. The engine cannot know which direction is "better" for your
+domain.
 
 ### Example: Exclusive Discount Groups
 
@@ -106,7 +139,6 @@ lexq groups delete --id <groupId> --force
 # Only one of these can fire per execution
 lexq groups create --json '{
   "name": "vip-discount",
-  "priority": 0,
   "activationGroup": "discounts",
   "activationMode": "EXCLUSIVE",
   "activationStrategy": "HIGHEST_PRIORITY"
@@ -114,11 +146,13 @@ lexq groups create --json '{
 
 lexq groups create --json '{
   "name": "seasonal-discount",
-  "priority": 1,
   "activationGroup": "discounts",
   "activationMode": "EXCLUSIVE",
   "activationStrategy": "HIGHEST_PRIORITY"
 }'
+
+# Groups are appended in creation order. Set it explicitly if it matters:
+#   lexq groups reorder --group-ids "<vipGid>,<seasonalGid>"
 ```
 
 ## A/B Testing
@@ -128,11 +162,14 @@ Split traffic between the current live version and a test version.
 ### Start A/B Test
 
 ```bash
-lexq groups ab-test start --group-id <groupId> --version-id <publishedVersionId> --traffic-rate 30
+lexq groups ab-test start --group-id <groupId> --version-id <activeVersionId> --traffic-rate 30
 ```
 
 `--traffic-rate` is the percentage (1–99) of traffic routed to the test version.
 
+The test version must be `ACTIVE` (published) and different from the live version. Starting a test cancels any pending
+scheduled deployment for the group.
+
 ### Adjust Traffic
 
 ```bash
@@ -156,7 +193,7 @@ This reverts all traffic to the main version. The test version remains ACTIVE bu
 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% → 100%
+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
 ```
@@ -168,10 +205,13 @@ This reverts all traffic to the main version. The test version remains ACTIVE bu
 Always list existing groups first to avoid duplicates:
 
 ```bash
-lexq groups list --format json | # parse and check if name exists
-lexq groups create --json '...'
+lexq groups list --size 100
+lexq groups create --json '{"name": "discount-policy"}'
 ```
 
+Group names are unique per tenant — a duplicate is rejected, not silently created. Listing first
+lets you reuse the existing group instead of handling the error.
+
 ### Emergency Stop
 
 ```bash