devlyn-cli 2.0.0 → 2.2.0

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/NOTES.md

@@ -0,0 +1,27 @@
+# F23 CLI fulfillment wave
+
+## Failure mode
+
+This fixture detects plausible allocators that pass simple order tests while
+missing production-critical interactions: priority before input order,
+all-or-nothing rollback, FEFO lot ordering, distance tie-breaks, and
+single-warehouse constraints.
+
+## Pipeline phase target
+
+PLAN must separate validation, order processing, tentative allocation, rollback,
+and final output sorting. IMPLEMENT must avoid partial mutation leaks. VERIFY
+should construct counterexamples where a partial allocation looks locally valid
+but corrupts later orders.
+
+## Why existing fixtures do not cover it
+
+F21 covers interval scheduling. F16 covers quote arithmetic. F22 was too easy
+for bare in the first calibration run. This fixture targets allocation rollback
+and inventory consumption across multiple dimensions.
+
+## Retirement
+
+Retire or replace if both bare and solo consistently exceed the headroom
+thresholds, or if a later logistics fixture provides the same rollback and
+allocation-order signal with less wall time.

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/expected.json

@@ -0,0 +1,56 @@
+{
+  "verification_commands": [
+    {
+      "cmd": "node --test tests/cli.test.js",
+      "exit_code": 0,
+      "stdout_contains": [],
+      "stdout_not_contains": ["not ok "]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/priority-rollback.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Process orders by `priority` descending, then `submitted_at` ascending, then `id` ascending.",
+        "An order is all-or-nothing. If any line cannot be fully allocated, reject the order and roll back all allocations tentatively made for that order.",
+        "Accepted allocations reduce stock for later orders in the same wave. Rejected orders do not reduce stock."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/single-warehouse-fefo.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "For a line where `single_warehouse` is `true`, the entire line quantity must come from one warehouse. It may use multiple lots inside that warehouse, but it must not split across warehouses.",
+        "Lot choice inside a warehouse is FEFO: `expires` ascending, then lot id ascending.",
+        "`remaining` is sorted by warehouse id, then sku, then expires, then lot."
+      ]
+    }
+  ],
+  "forbidden_patterns": [
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s+(null|undefined|''|\\{\\})",
+      "description": "silent catch returning fallback in fulfillment path",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    },
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
+      "description": "empty catch block",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    },
+    {
+      "pattern": "/\\*\\s*eslint-disable",
+      "description": "eslint-disable without scoped justification",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    }
+  ],
+  "required_files": ["bin/cli.js", "tests/cli.test.js"],
+  "forbidden_files": [],
+  "max_deps_added": 0,
+  "spec_output_files": ["bin/cli.js", "tests/cli.test.js"]
+}

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/metadata.json

@@ -0,0 +1,10 @@
+{
+  "id": "F23-cli-fulfillment-wave",
+  "category": "high-risk",
+  "difficulty": "high",
+  "timeout_seconds": 1500,
+  "required_tools": ["node"],
+  "browser": false,
+  "deps_change_expected": false,
+  "intent": "Add a bench-cli fulfill-wave command that allocates prioritized orders across warehouses and inventory lots using all-or-nothing order rollback, FEFO lot choice, distance tie-breaks, and single-warehouse line constraints."
+}

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/setup.sh

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+set -e

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/spec.md

@@ -0,0 +1,71 @@
+---
+id: "F23-cli-fulfillment-wave"
+title: "Fulfillment wave allocator"
+status: planned
+complexity: high
+depends-on: []
+---
+
+# F23 Fulfillment wave allocator
+
+## Context
+
+Add a `bench-cli fulfill-wave --input <path>` command that allocates
+prioritized orders across warehouses and inventory lots using all-or-nothing
+order rollback, FEFO lot choice, distance tie-breaks, and single-warehouse line
+constraints.
+
+The allocator prepares a batch for warehouse pickers. A plausible partial plan
+is worse than no plan: rejected orders must not consume stock, and accepted
+orders must be deterministic.
+
+## Requirements
+
+- [ ] `bench-cli fulfill-wave --input <path>` reads JSON shaped as `{ "warehouses": Array<Warehouse>, "orders": Array<Order> }`.
+- [ ] Each warehouse has `{ "id": string, "distance": number, "lots": Array<Lot> }`.
+- [ ] Each lot has `{ "sku": string, "lot": string, "qty": number, "expires": "YYYY-MM-DD" }`.
+- [ ] Each order has `{ "id": string, "priority": number, "submitted_at": string, "lines": Array<Line> }`.
+- [ ] Each line has `{ "sku": string, "qty": number, "single_warehouse": boolean }`.
+- [ ] Validate before allocation: ids are non-empty strings, quantities are positive integers, dates parse as ISO dates, priorities are numbers, and order ids are unique.
+- [ ] Process orders by `priority` descending, then `submitted_at` ascending, then `id` ascending.
+- [ ] An order is all-or-nothing. If any line cannot be fully allocated, reject the order and roll back all allocations tentatively made for that order.
+- [ ] For a normal line where `single_warehouse` is `false`, allocation may split across warehouses and lots.
+- [ ] For a line where `single_warehouse` is `true`, the entire line quantity must come from one warehouse. It may use multiple lots inside that warehouse, but it must not split across warehouses.
+- [ ] Warehouse choice order is `distance` ascending, then warehouse id ascending.
+- [ ] Lot choice inside a warehouse is FEFO: `expires` ascending, then lot id ascending.
+- [ ] Accepted allocations reduce stock for later orders in the same wave. Rejected orders do not reduce stock.
+- [ ] If an order cannot be fully allocated, reject with `{ "id": string, "reason": "insufficient_stock" }`.
+- [ ] Invalid input exits `2`, writes exactly one JSON error object to stderr, and writes nothing to stdout.
+- [ ] On success, write exactly one JSON object to stdout and no stderr. Keys: `accepted`, `rejected`, `remaining`.
+- [ ] `accepted` is ordered by processing order. Each accepted row has keys `id`, `allocations`.
+- [ ] Each allocation row has keys `sku`, `warehouse`, `lot`, `qty` and rows are ordered in the sequence stock was chosen.
+- [ ] `rejected` is ordered by original input order. Each rejected row has keys `id`, `reason`.
+- [ ] `remaining` is sorted by warehouse id, then sku, then expires, then lot. Each row has keys `warehouse`, `sku`, `lot`, `qty`, `expires`.
+- [ ] `tests/cli.test.js` is updated. Existing tests still pass AND at least two fulfill-wave tests cover one accepted allocation and one rejected all-or-nothing order.
+
+## Constraints
+
+- **No new npm dependencies.**
+- **No silent catches.** Invalid input and file-read failures must surface as JSON errors with exit `2`.
+- **No mutation of the input file.**
+- **No extra stdout/stderr text** on the success path; downstream tooling parses stdout as JSON.
+- **Touch only `bin/cli.js` and `tests/cli.test.js`.**
+- **Lifecycle note.** The harness's DOCS phase flips this spec's frontmatter `status` after implementation completes — that is benchmark lifecycle bookkeeping, not a scope violation.
+
+## Out of Scope
+
+- Carrier selection.
+- Package dimensions.
+- Backorders or partial order acceptance.
+- Persistence beyond stdout.
+- Touching `server/`, `web/`, or `tests/server.test.js`.
+
+## Verification
+
+- `node --test tests/cli.test.js` exits 0.
+- A higher-priority order consumes stock before a lower-priority order even when the lower-priority order appears first in the input.
+- A rejected order rolls back all tentative allocations and does not reduce stock available to later orders.
+- `single_warehouse: true` does not split a line across warehouses even if total stock across warehouses is enough.
+- Lot choice is FEFO by expiry date, then lot id.
+- `remaining` is sorted by warehouse id, then sku, then expires, then lot.
+- `git diff --stat` shows only `bin/cli.js` and `tests/cli.test.js` touched.

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/task.txt

@@ -0,0 +1,7 @@
+Add a `fulfill-wave` command to `bench-cli` so users can run `bench-cli fulfill-wave --input <path>` with a JSON file containing warehouses, inventory lots, and prioritized orders. It should allocate orders across warehouses and lots using all-or-nothing order rollback, FEFO lot choice, distance tie-breaks, and single-warehouse line constraints.
+
+Process orders by priority descending, then submitted_at ascending, then id ascending. Warehouse choice is distance ascending, then warehouse id ascending. Lot choice inside a warehouse is FEFO: expires ascending, then lot id ascending. Normal lines may split across warehouses and lots, but a line with `single_warehouse: true` must be fully allocated from one warehouse, though it may use multiple lots inside that warehouse. If any line in an order cannot be fully allocated, reject that order and roll back every tentative allocation for that order.
+
+On success, stdout must be exactly parseable JSON and stderr must be empty. The output has `accepted`, `rejected`, and `remaining`. Invalid input or file-read failures should exit `2`, print exactly one JSON error object to stderr, and print nothing to stdout.
+
+Update `tests/cli.test.js` so existing tests still pass and add at least two fulfill-wave tests: one accepted allocation and one rejected all-or-nothing order. No new npm dependencies. Only touch `bin/cli.js` and `tests/cli.test.js`.

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/verifiers/priority-rollback.js

@@ -0,0 +1,64 @@
+'use strict';
+const assert = require('node:assert');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const work = process.env.BENCH_WORKDIR || process.cwd();
+const cli = path.join(work, 'bin', 'cli.js');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'f23-wave-'));
+const input = path.join(tmp, 'wave.json');
+
+fs.writeFileSync(input, JSON.stringify({
+  warehouses: [
+    {
+      id: 'near',
+      distance: 1,
+      lots: [
+        { sku: 'A', lot: 'n-old', qty: 2, expires: '2026-02-01' },
+        { sku: 'B', lot: 'n-b', qty: 1, expires: '2026-02-01' }
+      ]
+    },
+    {
+      id: 'far',
+      distance: 9,
+      lots: [
+        { sku: 'A', lot: 'f-a', qty: 3, expires: '2026-01-15' }
+      ]
+    }
+  ],
+  orders: [
+    { id: 'low-first', priority: 1, submitted_at: '2026-01-01T09:00:00Z', lines: [{ sku: 'A', qty: 2, single_warehouse: false }] },
+    { id: 'bad-middle', priority: 5, submitted_at: '2026-01-01T09:01:00Z', lines: [{ sku: 'B', qty: 1, single_warehouse: false }, { sku: 'C', qty: 1, single_warehouse: false }] },
+    { id: 'high-second', priority: 10, submitted_at: '2026-01-01T09:02:00Z', lines: [{ sku: 'A', qty: 5, single_warehouse: false }] },
+    { id: 'after-bad', priority: 4, submitted_at: '2026-01-01T09:03:00Z', lines: [{ sku: 'B', qty: 1, single_warehouse: false }] }
+  ]
+}), 'utf8');
+
+const stdout = execFileSync('node', [cli, 'fulfill-wave', '--input', input], {
+  cwd: work,
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe']
+});
+const parsed = JSON.parse(stdout);
+assert.deepStrictEqual(parsed.accepted, [
+  {
+    id: 'high-second',
+    allocations: [
+        { sku: 'A', warehouse: 'near', lot: 'n-old', qty: 2 },
+        { sku: 'A', warehouse: 'far', lot: 'f-a', qty: 3 }
+    ]
+  },
+  {
+    id: 'after-bad',
+    allocations: [
+      { sku: 'B', warehouse: 'near', lot: 'n-b', qty: 1 }
+    ]
+  }
+]);
+assert.deepStrictEqual(parsed.rejected, [
+  { id: 'low-first', reason: 'insufficient_stock' },
+  { id: 'bad-middle', reason: 'insufficient_stock' }
+]);
+console.log(JSON.stringify({ ok: true }));

package/benchmark/auto-resolve/fixtures/F23-cli-fulfillment-wave/verifiers/single-warehouse-fefo.js

@@ -0,0 +1,66 @@
+'use strict';
+const assert = require('node:assert');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const work = process.env.BENCH_WORKDIR || process.cwd();
+const cli = path.join(work, 'bin', 'cli.js');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'f23-single-'));
+const input = path.join(tmp, 'wave.json');
+
+fs.writeFileSync(input, JSON.stringify({
+  warehouses: [
+    {
+      id: 'east',
+      distance: 2,
+      lots: [
+        { sku: 'K', lot: 'e-late', qty: 2, expires: '2026-04-01' },
+        { sku: 'K', lot: 'e-early', qty: 1, expires: '2026-03-01' }
+      ]
+    },
+    {
+      id: 'west',
+      distance: 1,
+      lots: [
+        { sku: 'K', lot: 'w-only', qty: 2, expires: '2026-02-01' },
+        { sku: 'Z', lot: 'w-z', qty: 1, expires: '2026-02-01' }
+      ]
+    }
+  ],
+  orders: [
+    { id: 'single-ok', priority: 10, submitted_at: '2026-01-01T09:00:00Z', lines: [{ sku: 'K', qty: 3, single_warehouse: true }] },
+    { id: 'single-reject', priority: 9, submitted_at: '2026-01-01T09:01:00Z', lines: [{ sku: 'K', qty: 3, single_warehouse: true }] },
+    { id: 'normal-z', priority: 8, submitted_at: '2026-01-01T09:02:00Z', lines: [{ sku: 'Z', qty: 1, single_warehouse: false }] }
+  ]
+}), 'utf8');
+
+const stdout = execFileSync('node', [cli, 'fulfill-wave', '--input', input], {
+  cwd: work,
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe']
+});
+const parsed = JSON.parse(stdout);
+assert.deepStrictEqual(parsed.accepted, [
+  {
+    id: 'single-ok',
+    allocations: [
+      { sku: 'K', warehouse: 'east', lot: 'e-early', qty: 1 },
+      { sku: 'K', warehouse: 'east', lot: 'e-late', qty: 2 }
+    ]
+  },
+  {
+    id: 'normal-z',
+    allocations: [
+      { sku: 'Z', warehouse: 'west', lot: 'w-z', qty: 1 }
+    ]
+  }
+]);
+assert.deepStrictEqual(parsed.rejected, [
+  { id: 'single-reject', reason: 'insufficient_stock' }
+]);
+assert.deepStrictEqual(parsed.remaining, [
+  { warehouse: 'west', sku: 'K', lot: 'w-only', qty: 2, expires: '2026-02-01' }
+]);
+console.log(JSON.stringify({ ok: true }));

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/NOTES.md

@@ -0,0 +1,28 @@
+# F25 CLI cart promotion rules
+
+## Failure mode
+
+This fixture detects checkout implementations that pass shallow cart tests while
+missing interaction invariants: duplicate-SKU aggregation, line-promotion order,
+order-coupon order, taxable base selection, free-shipping threshold timing, and
+externalized catalog data.
+
+## Pipeline phase target
+
+PLAN must preserve ordering between aggregation, validation, line promotions,
+coupon discount, tax, and shipping. IMPLEMENT must keep all money values in
+integer cents without new dependencies. VERIFY should execute adversarial cart
+examples rather than only checking a happy path.
+
+## Why existing fixtures do not cover it
+
+F16 covers quote tax rules, but not multiple line-promotion types plus an order
+coupon. F21/F23 cover scheduling/allocation but became oracle-control fixtures.
+This fixture keeps the F16-style fair visible-contract shape while testing a
+different checkout interaction.
+
+## Retirement
+
+Retire or replace this fixture if bare or solo consistently reaches ceiling, or
+if a later fixture covers the same promotion-order and catalog-source failure
+mode with cleaner full-pipeline lift.

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/expected.json

@@ -0,0 +1,66 @@
+{
+  "verification_commands": [
+    {
+      "cmd": "node --test tests/cli.test.js",
+      "exit_code": 0,
+      "stdout_contains": [],
+      "stdout_not_contains": ["not ok "]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/exact-success.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "A cart with duplicate SKUs combines quantities before stock validation and before line promotions.",
+        "A cart with both `buy_x_get_y_free` and `per_unit_discount_cents` line promotions applies those promotions before the order coupon.",
+        "Tax is computed from taxable item totals after line promotions and before the order coupon.",
+        "Shipping uses the subtotal after line discounts and coupon discount to decide whether the free-shipping threshold is met."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/stock-error.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Combined quantity over stock uses exact error shape `{ \"error\": \"invalid_stock\", \"sku\": string, \"available\": number, \"requested\": number }`.",
+        "The stock error object includes `sku`, `available`, and `requested`."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/catalog-source.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Catalog, stock, tax codes, line promotions, coupons, tax rates, shipping, and free-shipping threshold come from `data/catalog.json`. Do not hardcode these values in the command implementation.",
+        "Changing `data/catalog.json` prices or rates changes command output without code changes."
+      ]
+    }
+  ],
+  "forbidden_patterns": [
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s+(null|undefined|''|\\{\\})",
+      "description": "silent catch returning fallback in cart path",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    },
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{\\s*\\}",
+      "description": "empty catch block",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    },
+    {
+      "pattern": "/\\*\\s*eslint-disable",
+      "description": "eslint-disable without scoped justification",
+      "files": ["bin/cli.js"],
+      "severity": "disqualifier"
+    }
+  ],
+  "required_files": ["bin/cli.js", "tests/cli.test.js", "data/catalog.json"],
+  "forbidden_files": [],
+  "max_deps_added": 0,
+  "spec_output_files": ["bin/cli.js", "tests/cli.test.js"]
+}

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/metadata.json

@@ -0,0 +1,10 @@
+{
+  "id": "F25-cli-cart-promotion-rules",
+  "category": "high-risk",
+  "difficulty": "high",
+  "timeout_seconds": 1500,
+  "required_tools": ["node"],
+  "browser": false,
+  "deps_change_expected": false,
+  "intent": "Add a bench-cli cart command that reads a cart JSON file, prices it from data/catalog.json, combines duplicate SKU quantities, applies line promotions before an order coupon, and prints one exact JSON total with cents-based discounts, tax, shipping, and item rows."
+}

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/setup.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# F25 setup — seed cart catalog and promotion rules.
+set -e
+
+mkdir -p data
+
+cat > data/catalog.json <<'JSON'
+{
+  "products": {
+    "TEE": { "unit_cents": 2500, "stock": 10, "tax_code": "standard" },
+    "BAG": { "unit_cents": 3200, "stock": 4, "tax_code": "standard" },
+    "MUG": { "unit_cents": 1200, "stock": 20, "tax_code": "exempt" }
+  },
+  "line_promotions": [
+    { "sku": "TEE", "type": "buy_x_get_y_free", "buy_qty": 2, "free_qty": 1 },
+    { "sku": "BAG", "type": "per_unit_discount_cents", "min_qty": 2, "per_unit_discount_cents": 500 }
+  ],
+  "coupons": {
+    "ORDER10": { "percent": 10, "min_subtotal_cents": 8000 },
+    "SMALL5": { "percent": 5, "min_subtotal_cents": 2000 }
+  },
+  "tax_rates": {
+    "CA": 0.0825,
+    "OR": 0,
+    "NY": 0.08875
+  },
+  "taxable_codes": {
+    "standard": true,
+    "exempt": false
+  },
+  "shipping_cents": 699,
+  "free_shipping_min_cents": 9000
+}
+JSON
+
+exit 0

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/spec.md

@@ -0,0 +1,65 @@
+---
+id: "F25-cli-cart-promotion-rules"
+title: "Cart command with promotion rules"
+status: planned
+complexity: high
+depends-on: []
+---
+
+# F25 Cart command with promotion rules
+
+## Context
+
+`bench-cli` currently has greeting and version commands only. The task:
+add a `cart` command that reads a cart JSON file, prices it from
+`data/catalog.json`, combines duplicate SKU quantities, applies line promotions
+before an order coupon, and prints one exact JSON total with cents-based
+discounts, tax, shipping, and item rows.
+
+This is checkout promotion math, so every public amount must be integer cents
+and stdout must stay machine-readable.
+
+## Requirements
+
+- [ ] `bench-cli cart --input <path>` reads JSON shaped as `{ "state": string, "coupon": string | null, "items": [{ "sku": string, "qty": number }] }`.
+- [ ] Catalog, stock, tax codes, line promotions, coupons, tax rates, shipping, and free-shipping threshold come from `data/catalog.json`. Do not hardcode these values in the command implementation.
+- [ ] Combine duplicate SKUs before validating stock and before applying line promotions. The output `items` array must contain one row per SKU in first-seen order.
+- [ ] Validation happens before any cart total is printed. Invalid JSON, missing `items`, unknown SKU, non-positive or non-integer `qty`, combined quantity over stock, unknown coupon, or unknown state exits `2` and writes exactly one JSON error object to stderr.
+- [ ] Combined quantity over stock uses exact error shape `{ "error": "invalid_stock", "sku": string, "available": number, "requested": number }`.
+- [ ] On success, write exactly one JSON object to stdout and no stderr. Keys: `subtotal_cents`, `line_discount_cents`, `coupon_discount_cents`, `tax_cents`, `shipping_cents`, `total_cents`, `items`.
+- [ ] Each output item row has keys `sku`, `qty`, `line_subtotal_cents`, `line_discount_cents`, and `line_total_cents`.
+- [ ] Line promotion `buy_x_get_y_free` applies to the configured SKU as `Math.floor(qty / (buy_qty + free_qty)) * free_qty * unit_cents`.
+- [ ] Line promotion `per_unit_discount_cents` applies to the configured SKU only when combined `qty >= min_qty`, and the discount is `per_unit_discount_cents * qty`.
+- [ ] `line_discount_cents` is the sum of all item line discounts; each `line_total_cents` is `line_subtotal_cents - line_discount_cents` for that item.
+- [ ] `coupon_discount_cents` is `Math.round((subtotal_cents - line_discount_cents) * coupon.percent / 100)` when a coupon is present and the post-line-discount subtotal meets `coupon.min_subtotal_cents`; otherwise `0`.
+- [ ] Tax is computed after line promotions and before the order coupon. A product is taxable when its `tax_code` maps to `true` in `catalog.taxable_codes`. Tax rate is `catalog.tax_rates[state]`. Use `Math.round(taxable_post_line_discount_cents * rate)`.
+- [ ] `shipping_cents` is `0` when `subtotal_cents - line_discount_cents - coupon_discount_cents >= catalog.free_shipping_min_cents`; otherwise use `catalog.shipping_cents`.
+- [ ] `total_cents = subtotal_cents - line_discount_cents - coupon_discount_cents + tax_cents + shipping_cents`.
+- [ ] `tests/cli.test.js` is updated. Existing tests still pass AND at least two new tests cover `cart`: one successful cart and one validation failure.
+
+## Constraints
+
+- **No new npm dependencies.**
+- **No floating-money output.** All public amounts are integer cents.
+- **No silent catches.** If parsing or file reading fails, emit a visible JSON error to stderr and exit `2`.
+- **No extra stdout/stderr text** on the success path; downstream tooling parses stdout as JSON.
+- **Lifecycle note.** The harness's DOCS phase flips this spec's frontmatter `status` after implementation completes — that is benchmark lifecycle bookkeeping, not a scope violation.
+
+## Out of Scope
+
+- Inventory mutation or order persistence.
+- Adding currencies, locales, or tax jurisdictions beyond `catalog.tax_rates`.
+- Adding web UI or server routes.
+- Touching `server/`, `web/`, or `tests/server.test.js`.
+
+## Verification
+
+- `node --test tests/cli.test.js` exits 0.
+- A cart with duplicate SKUs combines quantities before stock validation and before line promotions.
+- A cart with both `buy_x_get_y_free` and `per_unit_discount_cents` line promotions applies those promotions before the order coupon.
+- Tax is computed from taxable item totals after line promotions and before the order coupon.
+- Shipping uses the subtotal after line discounts and coupon discount to decide whether the free-shipping threshold is met.
+- A cart over combined stock exits `2`, prints one JSON error to stderr, and prints no stdout.
+- The stock error object includes `sku`, `available`, and `requested`.
+- Changing `data/catalog.json` prices or rates changes command output without code changes.
+- `git diff --stat` shows only `bin/cli.js` and `tests/cli.test.js` touched (the catalog seed comes from setup, not the arm).

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/task.txt

@@ -0,0 +1,7 @@
+Add a bench-cli cart command that reads a cart JSON file, prices it from data/catalog.json, combines duplicate SKU quantities, applies line promotions before an order coupon, and prints one exact JSON total with cents-based discounts, tax, shipping, and item rows.
+
+The command should be `bench-cli cart --input <path>`. The input JSON has a state, an optional coupon, and item rows with sku and qty. Use integer cents for every public amount. Read all catalog data from `data/catalog.json`; do not hardcode products, stock, tax codes, promotions, coupons, tax rates, shipping, or the free-shipping threshold.
+
+Duplicate SKUs must be combined before stock validation and before promotion math. On success, stdout must be exactly one JSON object with subtotal, line discount, coupon discount, tax, shipping, total, and one item row per SKU in first-seen order. Validation errors must exit 2, print exactly one JSON error object to stderr, and print no stdout. Combined stock errors must include the sku, available quantity, and requested combined quantity.
+
+Update `tests/cli.test.js` so existing tests still pass and at least two new tests cover the cart command, including one successful cart and one validation failure. Do not add dependencies or touch the server/web files.

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/verifiers/catalog-source.js

@@ -0,0 +1,57 @@
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const workdir = process.env.BENCH_WORKDIR || process.cwd();
+const catalogPath = path.join(workdir, 'data', 'catalog.json');
+const original = fs.readFileSync(catalogPath, 'utf8');
+
+try {
+  const catalog = JSON.parse(original);
+  catalog.products.TEE.unit_cents = 3333;
+  catalog.products.TEE.stock = 7;
+  catalog.tax_rates.OR = 0;
+  catalog.line_promotions = [];
+  catalog.coupons = {};
+  catalog.shipping_cents = 777;
+  catalog.free_shipping_min_cents = 99999;
+  fs.writeFileSync(catalogPath, JSON.stringify(catalog, null, 2) + '\n');
+
+  const input = path.join(os.tmpdir(), `cart-source-${process.pid}.json`);
+  fs.writeFileSync(input, JSON.stringify({
+    state: 'OR',
+    coupon: null,
+    items: [{ sku: 'TEE', qty: 1 }]
+  }));
+
+  const proc = spawnSync('node', ['bin/cli.js', 'cart', '--input', input], {
+    cwd: workdir,
+    encoding: 'utf8'
+  });
+
+  assert.strictEqual(proc.status, 0, proc.stderr || proc.stdout);
+  assert.strictEqual(proc.stderr, '');
+  assert.deepStrictEqual(JSON.parse(proc.stdout), {
+    subtotal_cents: 3333,
+    line_discount_cents: 0,
+    coupon_discount_cents: 0,
+    tax_cents: 0,
+    shipping_cents: 777,
+    total_cents: 4110,
+    items: [
+      {
+        sku: 'TEE',
+        qty: 1,
+        line_subtotal_cents: 3333,
+        line_discount_cents: 0,
+        line_total_cents: 3333
+      }
+    ]
+  });
+} finally {
+  fs.writeFileSync(catalogPath, original);
+}
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/verifiers/exact-success.js

@@ -0,0 +1,63 @@
+const assert = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const workdir = process.env.BENCH_WORKDIR || process.cwd();
+const input = path.join(os.tmpdir(), `cart-success-${process.pid}.json`);
+
+fs.writeFileSync(input, JSON.stringify({
+  state: 'CA',
+  coupon: 'ORDER10',
+  items: [
+    { sku: 'TEE', qty: 2 },
+    { sku: 'BAG', qty: 1 },
+    { sku: 'TEE', qty: 1 },
+    { sku: 'MUG', qty: 2 },
+    { sku: 'BAG', qty: 1 }
+  ]
+}));
+
+const proc = spawnSync('node', ['bin/cli.js', 'cart', '--input', input], {
+  cwd: workdir,
+  encoding: 'utf8'
+});
+
+assert.strictEqual(proc.status, 0, proc.stderr || proc.stdout);
+assert.strictEqual(proc.stderr, '');
+
+const actual = JSON.parse(proc.stdout);
+assert.deepStrictEqual(actual, {
+  subtotal_cents: 16300,
+  line_discount_cents: 3500,
+  coupon_discount_cents: 1280,
+  tax_cents: 858,
+  shipping_cents: 0,
+  total_cents: 12378,
+  items: [
+    {
+      sku: 'TEE',
+      qty: 3,
+      line_subtotal_cents: 7500,
+      line_discount_cents: 2500,
+      line_total_cents: 5000
+    },
+    {
+      sku: 'BAG',
+      qty: 2,
+      line_subtotal_cents: 6400,
+      line_discount_cents: 1000,
+      line_total_cents: 5400
+    },
+    {
+      sku: 'MUG',
+      qty: 2,
+      line_subtotal_cents: 2400,
+      line_discount_cents: 0,
+      line_total_cents: 2400
+    }
+  ]
+});
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');