devlyn-cli 2.0.0 → 2.2.0

package/benchmark/auto-resolve/fixtures/F25-cli-cart-promotion-rules/verifiers/stock-error.js

@@ -0,0 +1,34 @@
+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-stock-${process.pid}.json`);
+
+fs.writeFileSync(input, JSON.stringify({
+  state: 'OR',
+  coupon: null,
+  items: [
+    { sku: 'BAG', qty: 2 },
+    { sku: 'MUG', qty: 1 },
+    { sku: 'BAG', qty: 3 }
+  ]
+}));
+
+const proc = spawnSync('node', ['bin/cli.js', 'cart', '--input', input], {
+  cwd: workdir,
+  encoding: 'utf8'
+});
+
+assert.strictEqual(proc.status, 2);
+assert.strictEqual(proc.stdout, '');
+assert.deepStrictEqual(JSON.parse(proc.stderr), {
+  error: 'invalid_stock',
+  sku: 'BAG',
+  available: 4,
+  requested: 5
+});
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/NOTES.md

@@ -0,0 +1,25 @@
+# F26 CLI payout ledger rules
+
+## Failure mode
+
+This fixture detects settlement implementations that pass simple payout tests
+while mishandling idempotent events, conflicting duplicates, fee ordering,
+dispute fees, reserves, minimum payout holds, and top-level totals.
+
+## Pipeline phase target
+
+PLAN must preserve event deduplication and arithmetic order. IMPLEMENT must keep
+fee/reserve math in integer cents and avoid hardcoded rules. VERIFY should build
+adversarial ledger examples with repeated IDs, refunds, disputes, and reserves.
+
+## Why existing fixtures do not cover it
+
+F16 covers quote math and F25 covers cart promotions, but neither has ledger
+idempotency or conflicting duplicate events. F21/F23 became oracle-control
+fixtures, so this adds a fresh visible-contract stateful arithmetic candidate.
+
+## Retirement
+
+Retire or replace this fixture if solo consistently reaches ceiling or if
+another fixture provides the same idempotent-ledger signal with cleaner
+full-pipeline pair lift.

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/expected.json

@@ -0,0 +1,68 @@
+{
+  "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-payout.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Identical duplicate event IDs are applied only once before merchant totals are computed.",
+        "A payout with charges, a refund, and a dispute computes processing fees, dispute fees, reserves, merchant payouts, and top-level totals exactly.",
+        "Processing fees apply to charges only; refunds do not reverse processing fees.",
+        "Dispute events subtract the dispute amount and add one dispute fee per dispute event.",
+        "Merchant rows preserve first-seen merchant order after idempotent duplicate removal."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/conflicting-duplicate.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Conflicting duplicate events use exact error shape `{ \"error\": \"conflicting_duplicate\", \"id\": string }`.",
+        "A conflicting duplicate exits `2`, prints one JSON error to stderr, and prints no stdout.",
+        "The conflicting duplicate error object includes `error` and `id`."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/rules-source.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Processing fee percent, fixed fee, dispute fee, reserve percent, and minimum payout threshold come from `data/payout-rules.json`. Do not hardcode these values in the command implementation.",
+        "Changing `data/payout-rules.json` fee or reserve settings changes command output without code changes."
+      ]
+    }
+  ],
+  "forbidden_patterns": [
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s+(null|undefined|''|\\{\\})",
+      "description": "silent catch returning fallback in payout 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/payout-rules.json"],
+  "forbidden_files": [],
+  "max_deps_added": 0,
+  "spec_output_files": ["bin/cli.js", "tests/cli.test.js"]
+}

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/metadata.json

@@ -0,0 +1,10 @@
+{
+  "id": "F26-cli-payout-ledger-rules",
+  "category": "high-risk",
+  "difficulty": "high",
+  "timeout_seconds": 1500,
+  "required_tools": ["node"],
+  "browser": false,
+  "deps_change_expected": false,
+  "intent": "Add a bench-cli payout command that reads ledger events from a JSON file, applies idempotent event handling and payout rules from data/payout-rules.json, and prints exact merchant payout totals with processing fees, dispute fees, reserves, and payouts in integer cents."
+}

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/setup.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# F26 setup — seed payout ledger rules.
+set -e
+
+mkdir -p data
+
+cat > data/payout-rules.json <<'JSON'
+{
+  "processing_fee_percent": 2.9,
+  "fixed_fee_cents": 30,
+  "dispute_fee_cents": 1500,
+  "reserve_percent": 10,
+  "minimum_payout_cents": 1000
+}
+JSON
+
+exit 0

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/spec.md

@@ -0,0 +1,69 @@
+---
+id: "F26-cli-payout-ledger-rules"
+title: "Payout command with ledger rules"
+status: planned
+complexity: high
+depends-on: []
+---
+
+# F26 Payout command with ledger rules
+
+## Context
+
+`bench-cli` currently has greeting and version commands only. The task:
+add a `payout` command that reads ledger events from a JSON file, applies
+idempotent event handling and payout rules from `data/payout-rules.json`, and
+prints exact merchant payout totals with processing fees, dispute fees,
+reserves, and payouts in integer cents.
+
+This is settlement math, so duplicate events must not corrupt totals and every
+public amount must be integer cents.
+
+## Requirements
+
+- [ ] `bench-cli payout --input <path>` reads JSON shaped as `{ "events": [{ "id": string, "merchant_id": string, "type": "charge" | "refund" | "dispute", "amount_cents": number }] }`.
+- [ ] Processing fee percent, fixed fee, dispute fee, reserve percent, and minimum payout threshold come from `data/payout-rules.json`. Do not hardcode these values in the command implementation.
+- [ ] Events with the same `id` and identical JSON content are idempotent duplicates and are applied only once.
+- [ ] Events with the same `id` but different JSON content are conflicting duplicates. Validation happens before payout totals are printed, exits `2`, writes exactly one JSON error object to stderr, and writes no stdout.
+- [ ] Conflicting duplicate events use exact error shape `{ "error": "conflicting_duplicate", "id": string }`.
+- [ ] Unknown event type, missing `merchant_id`, missing `id`, non-positive or non-integer `amount_cents`, missing `events`, invalid JSON, or unreadable input exits `2` and writes exactly one JSON error object to stderr.
+- [ ] Merchant rows are emitted in first-seen merchant order after idempotent duplicate removal.
+- [ ] A `charge` increases `gross_charge_cents` and adds a processing fee of `Math.round(amount_cents * processing_fee_percent / 100) + fixed_fee_cents`.
+- [ ] A `refund` increases `refund_cents`. Refunds do not reverse processing fees.
+- [ ] A `dispute` increases `dispute_cents` and adds `dispute_fee_cents` from the rules for each dispute event.
+- [ ] For each merchant, compute `net_before_reserve = gross_charge_cents - refund_cents - dispute_cents - processing_fee_cents - dispute_fee_cents`.
+- [ ] `reserve_cents` is `Math.round(net_before_reserve * reserve_percent / 100)` when `net_before_reserve > 0`; otherwise `0`.
+- [ ] `payout_cents = net_before_reserve - reserve_cents`.
+- [ ] If `0 < payout_cents < minimum_payout_cents`, keep the merchant row but set `payout_cents` to `0` and add the original positive amount into `reserve_cents`.
+- [ ] On success, write exactly one JSON object to stdout and no stderr. Keys: `total_payout_cents`, `total_processing_fee_cents`, `total_dispute_fee_cents`, `total_reserve_cents`, `merchants`.
+- [ ] Each merchant row has keys `merchant_id`, `gross_charge_cents`, `refund_cents`, `dispute_cents`, `processing_fee_cents`, `dispute_fee_cents`, `reserve_cents`, `payout_cents`.
+- [ ] `tests/cli.test.js` is updated. Existing tests still pass AND at least two new tests cover `payout`: one successful payout 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
+
+- Persisting payouts or mutating a ledger.
+- Currency conversion.
+- Time zones, reporting periods, or settlement dates.
+- Adding web UI or server routes.
+- Touching `server/`, `web/`, or `tests/server.test.js`.
+
+## Verification
+
+- `node --test tests/cli.test.js` exits 0.
+- Identical duplicate event IDs are applied only once before merchant totals are computed.
+- A payout with charges, a refund, and a dispute computes processing fees, dispute fees, reserves, merchant payouts, and top-level totals exactly.
+- Processing fees apply to charges only; refunds do not reverse processing fees.
+- Dispute events subtract the dispute amount and add one dispute fee per dispute event.
+- Merchant rows preserve first-seen merchant order after idempotent duplicate removal.
+- A conflicting duplicate exits `2`, prints one JSON error to stderr, and prints no stdout.
+- The conflicting duplicate error object includes `error` and `id`.
+- Changing `data/payout-rules.json` fee or reserve settings changes command output without code changes.
+- `git diff --stat` shows only `bin/cli.js` and `tests/cli.test.js` touched (the payout rules seed comes from setup, not the arm).

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/task.txt

@@ -0,0 +1,7 @@
+Add a bench-cli payout command that reads ledger events from a JSON file, applies idempotent event handling and payout rules from data/payout-rules.json, and prints exact merchant payout totals with processing fees, dispute fees, reserves, and payouts in integer cents.
+
+The command should be `bench-cli payout --input <path>`. Input JSON has an events array. Events have id, merchant_id, type, and amount_cents. Use the payout rules JSON for processing fee percent, fixed fee, dispute fee, reserve percent, and minimum payout threshold. Do not hardcode those values.
+
+Identical duplicate event IDs are idempotent and should be applied only once. The same event ID with different content is a conflicting duplicate and must fail before printing totals. Successful output must be one JSON object with top-level totals and merchant rows in first-seen merchant order. Validation errors must exit 2, write one JSON error object to stderr, and write no stdout.
+
+Update `tests/cli.test.js` so existing tests still pass and at least two new tests cover the payout command, including one successful payout and one validation failure. Do not add dependencies or touch the server/web files.

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/verifiers/conflicting-duplicate.js

@@ -0,0 +1,29 @@
+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(), `payout-conflict-${process.pid}.json`);
+
+fs.writeFileSync(input, JSON.stringify({
+  events: [
+    { id: 'evt-conflict', merchant_id: 'm_1', type: 'charge', amount_cents: 1000 },
+    { id: 'evt-conflict', merchant_id: 'm_1', type: 'charge', amount_cents: 1001 }
+  ]
+}));
+
+const proc = spawnSync('node', ['bin/cli.js', 'payout', '--input', input], {
+  cwd: workdir,
+  encoding: 'utf8'
+});
+
+assert.strictEqual(proc.status, 2);
+assert.strictEqual(proc.stdout, '');
+assert.deepStrictEqual(JSON.parse(proc.stderr), {
+  error: 'conflicting_duplicate',
+  id: 'evt-conflict'
+});
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/verifiers/exact-payout.js

@@ -0,0 +1,58 @@
+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(), `payout-success-${process.pid}.json`);
+
+const charge1 = { id: 'evt-1', merchant_id: 'm_1', type: 'charge', amount_cents: 10000 };
+fs.writeFileSync(input, JSON.stringify({
+  events: [
+    charge1,
+    { id: 'evt-2', merchant_id: 'm_2', type: 'charge', amount_cents: 5000 },
+    charge1,
+    { id: 'evt-3', merchant_id: 'm_1', type: 'refund', amount_cents: 2500 },
+    { id: 'evt-4', merchant_id: 'm_1', type: 'charge', amount_cents: 3333 },
+    { id: 'evt-5', merchant_id: 'm_2', type: 'dispute', amount_cents: 2000 }
+  ]
+}));
+
+const proc = spawnSync('node', ['bin/cli.js', 'payout', '--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), {
+  total_payout_cents: 10539,
+  total_processing_fee_cents: 622,
+  total_dispute_fee_cents: 1500,
+  total_reserve_cents: 1172,
+  merchants: [
+    {
+      merchant_id: 'm_1',
+      gross_charge_cents: 13333,
+      refund_cents: 2500,
+      dispute_cents: 0,
+      processing_fee_cents: 447,
+      dispute_fee_cents: 0,
+      reserve_cents: 1039,
+      payout_cents: 9347
+    },
+    {
+      merchant_id: 'm_2',
+      gross_charge_cents: 5000,
+      refund_cents: 0,
+      dispute_cents: 2000,
+      processing_fee_cents: 175,
+      dispute_fee_cents: 1500,
+      reserve_cents: 133,
+      payout_cents: 1192
+    }
+  ]
+});
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');

package/benchmark/auto-resolve/fixtures/F26-cli-payout-ledger-rules/verifiers/rules-source.js

@@ -0,0 +1,56 @@
+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 rulesPath = path.join(workdir, 'data', 'payout-rules.json');
+const original = fs.readFileSync(rulesPath, 'utf8');
+
+try {
+  fs.writeFileSync(rulesPath, JSON.stringify({
+    processing_fee_percent: 1,
+    fixed_fee_cents: 10,
+    dispute_fee_cents: 77,
+    reserve_percent: 0,
+    minimum_payout_cents: 1
+  }, null, 2) + '\n');
+
+  const input = path.join(os.tmpdir(), `payout-rules-${process.pid}.json`);
+  fs.writeFileSync(input, JSON.stringify({
+    events: [
+      { id: 'evt-1', merchant_id: 'm_1', type: 'charge', amount_cents: 10000 }
+    ]
+  }));
+
+  const proc = spawnSync('node', ['bin/cli.js', 'payout', '--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), {
+    total_payout_cents: 9890,
+    total_processing_fee_cents: 110,
+    total_dispute_fee_cents: 0,
+    total_reserve_cents: 0,
+    merchants: [
+      {
+        merchant_id: 'm_1',
+        gross_charge_cents: 10000,
+        refund_cents: 0,
+        dispute_cents: 0,
+        processing_fee_cents: 110,
+        dispute_fee_cents: 0,
+        reserve_cents: 0,
+        payout_cents: 9890
+      }
+    ]
+  });
+} finally {
+  fs.writeFileSync(rulesPath, original);
+}
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/NOTES.md

@@ -0,0 +1,24 @@
+# F27 CLI gift card redemption
+
+## Why this fixture exists
+
+F16 showed a valid full-pipeline pair lift when the solo arm implemented the
+happy path but missed the exact validation-error contract. F25 was rejected
+after an oracle correction made solo pass. F26 was rejected because solo reached
+the ceiling.
+
+F27 keeps the useful F16 shape but removes checkout tax complexity: success is
+straight integer aggregation, while the risk is the exact failure object after
+combining duplicate card redemption rows before balance validation.
+
+## Pair expectation
+
+PLAN must preserve the order of aggregation before validation. IMPLEMENT must
+read `data/gift-cards.json` and keep all public amounts in integer cents.
+VERIFY should construct an adversarial request where two individually valid
+redemptions for the same card become invalid only after combination.
+
+## Isolation
+
+F16 covers quote tax rules. F27 covers non-persistent balance redemption and
+exact validation shape after duplicate aggregation.

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/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": [
+        "Duplicate SKUs are combined before line totals are computed.",
+        "A successful redemption emits exact item rows, redemption rows, applied total, and amount due.",
+        "On success, write exactly one JSON object to stdout and no stderr. Keys: `order_id`, `subtotal_cents`, `gift_card_applied_cents`, `amount_due_cents`, `items`, `redemptions`."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/insufficient-balance.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Duplicate `card_id` redemption rows are combined before balance validation.",
+        "Combined card redemption over balance uses exact error shape `{ \"error\": \"insufficient_balance\", \"card_id\": string, \"available_cents\": number, \"requested_cents\": number }`.",
+        "The insufficient balance error object includes `error`, `card_id`, `available_cents`, and `requested_cents`."
+      ]
+    },
+    {
+      "cmd": "node \"$BENCH_FIXTURE_DIR/verifiers/rules-source.js\"",
+      "exit_code": 0,
+      "stdout_contains": ["\"ok\":true"],
+      "stdout_not_contains": [],
+      "contract_refs": [
+        "Product prices, gift-card balances, and gift-card active flags come from `data/gift-cards.json`. Do not hardcode product prices, card balances, or active flags in the command implementation.",
+        "Changing `data/gift-cards.json` product prices or card balances changes command output without code changes."
+      ]
+    }
+  ],
+  "forbidden_patterns": [
+    {
+      "pattern": "catch\\s*\\([^)]*\\)\\s*\\{[^}]*return\\s+(null|undefined|''|\\{\\})",
+      "description": "silent catch returning fallback in gift-card 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/gift-cards.json"],
+  "forbidden_files": [],
+  "max_deps_added": 0,
+  "spec_output_files": ["bin/cli.js", "tests/cli.test.js"]
+}

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/metadata.json

@@ -0,0 +1,10 @@
+{
+  "id": "F27-cli-gift-card-redemption",
+  "category": "high-risk",
+  "difficulty": "high",
+  "timeout_seconds": 1500,
+  "required_tools": ["node"],
+  "browser": false,
+  "deps_change_expected": false,
+  "intent": "Add a bench-cli gift-card command that reads cart lines and gift-card redemption requests, prices products from data/gift-cards.json, combines duplicate SKUs and duplicate card redemptions before validation, and prints exact remaining balances and amount due in integer cents."
+}

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/setup.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# F27 setup - seed gift card product and balance rules.
+set -e
+
+mkdir -p data
+
+cat > data/gift-cards.json <<'JSON'
+{
+  "products": {
+    "TEE": { "unit_cents": 2500 },
+    "SOCKS": { "unit_cents": 700 },
+    "BAG": { "unit_cents": 3200 }
+  },
+  "cards": {
+    "GC-100": { "balance_cents": 5000, "active": true },
+    "GC-200": { "balance_cents": 2500, "active": true },
+    "GC-LOCKED": { "balance_cents": 9999, "active": false }
+  }
+}
+JSON
+
+exit 0

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/spec.md

@@ -0,0 +1,62 @@
+---
+id: "F27-cli-gift-card-redemption"
+title: "Gift card command with redemption rules"
+status: planned
+complexity: high
+depends-on: []
+---
+
+# F27 Gift card command with redemption rules
+
+## Context
+
+`bench-cli` currently has greeting and version commands only. The task:
+add a `gift-card` command that reads cart lines and gift-card redemption
+requests from a JSON file, prices products from `data/gift-cards.json`, and
+prints exact gift-card application totals in integer cents.
+
+Gift-card balances are money-like state, so duplicate line and redemption
+requests must be combined before validation. The command only calculates the
+result; it does not persist balance changes.
+
+## Requirements
+
+- [ ] `bench-cli gift-card --input <path>` reads JSON shaped as `{ "order_id": string, "lines": [{ "sku": string, "qty": number }], "redeems": [{ "card_id": string, "amount_cents": number }] }`.
+- [ ] Product prices, gift-card balances, and gift-card active flags come from `data/gift-cards.json`. Do not hardcode product prices, card balances, or active flags in the command implementation.
+- [ ] Combine duplicate SKUs before computing line totals. The output `items` array must contain one row per SKU in first-seen order.
+- [ ] Combine duplicate `card_id` redemption requests before validating balances and before computing remaining balances. The output `redemptions` array must contain one row per card in first-seen order.
+- [ ] Validation happens before any result is printed. Invalid JSON, missing `lines`, missing `redeems`, unknown SKU, unknown card, inactive card, non-positive or non-integer `qty`, non-positive or non-integer `amount_cents`, missing `order_id`, combined card redemption over balance, or total redemption over subtotal exits `2` and writes exactly one JSON error object to stderr.
+- [ ] Combined card redemption over balance uses exact error shape `{ "error": "insufficient_balance", "card_id": string, "available_cents": number, "requested_cents": number }`.
+- [ ] Total redemption over subtotal uses exact error shape `{ "error": "redemption_exceeds_subtotal", "subtotal_cents": number, "requested_cents": number }`.
+- [ ] On success, write exactly one JSON object to stdout and no stderr. Keys: `order_id`, `subtotal_cents`, `gift_card_applied_cents`, `amount_due_cents`, `items`, `redemptions`.
+- [ ] Each output item row has keys `sku`, `qty`, `line_cents`. `line_cents` is `unit_cents * combined_qty`.
+- [ ] Each redemption row has keys `card_id`, `applied_cents`, `remaining_balance_cents`. `remaining_balance_cents` is the starting balance from `data/gift-cards.json` minus the combined requested redemption for that card.
+- [ ] `gift_card_applied_cents` is the sum of combined redemption amounts.
+- [ ] `amount_due_cents = subtotal_cents - gift_card_applied_cents`.
+- [ ] `tests/cli.test.js` is updated. Existing tests still pass AND at least two new tests cover `gift-card`: one successful redemption 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
+
+- Persisting changed gift-card balances.
+- Taxes, shipping, coupons, or currencies beyond integer cents.
+- Adding server routes or web UI.
+- Touching `server/`, `web/`, or `tests/server.test.js`.
+
+## Verification
+
+- `node --test tests/cli.test.js` exits 0.
+- Duplicate SKUs are combined before line totals are computed.
+- Duplicate `card_id` redemption rows are combined before balance validation.
+- A successful redemption emits exact item rows, redemption rows, applied total, and amount due.
+- Changing `data/gift-cards.json` product prices or card balances changes command output without code changes.
+- A combined card redemption over balance exits `2`, prints one JSON error to stderr, and prints no stdout.
+- The insufficient balance error object includes `error`, `card_id`, `available_cents`, and `requested_cents`.
+- `git diff --stat` shows only `bin/cli.js` and `tests/cli.test.js` touched (the gift-card seed comes from setup, not the arm).

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/task.txt

@@ -0,0 +1,9 @@
+Add a `gift-card` command to `bench-cli` so users can run `bench-cli gift-card --input <path>` with a JSON file shaped as `{ "order_id": string, "lines": [{ "sku": string, "qty": number }], "redeems": [{ "card_id": string, "amount_cents": number }] }`.
+
+Read product prices, card balances, and active flags from `data/gift-cards.json`. Do not hardcode those values. Combine duplicate SKUs before computing line totals, and combine duplicate `card_id` redemption requests before validating balances or computing remaining balances.
+
+On success, write one JSON object to stdout and no stderr with keys `order_id`, `subtotal_cents`, `gift_card_applied_cents`, `amount_due_cents`, `items`, and `redemptions`. Item rows have `sku`, `qty`, `line_cents`. Redemption rows have `card_id`, `applied_cents`, `remaining_balance_cents`. Preserve first-seen order for combined SKU rows and combined card rows.
+
+Validation happens before any result is printed. Invalid JSON, missing `lines`, missing `redeems`, unknown SKU, unknown card, inactive card, non-positive or non-integer `qty`, non-positive or non-integer `amount_cents`, missing `order_id`, combined card redemption over balance, or total redemption over subtotal exits `2` and writes exactly one JSON error object to stderr. Combined card redemption over balance must use exact shape `{ "error": "insufficient_balance", "card_id": string, "available_cents": number, "requested_cents": number }`. Total redemption over subtotal must use exact shape `{ "error": "redemption_exceeds_subtotal", "subtotal_cents": number, "requested_cents": number }`.
+
+Update `tests/cli.test.js` so existing tests still pass and at least two new tests cover `gift-card`: one successful redemption and one validation failure.

package/benchmark/auto-resolve/fixtures/F27-cli-gift-card-redemption/verifiers/exact-success.js

@@ -0,0 +1,48 @@
+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(), `gift-card-success-${process.pid}.json`);
+
+fs.writeFileSync(input, JSON.stringify({
+  order_id: 'order-27',
+  lines: [
+    { sku: 'TEE', qty: 1 },
+    { sku: 'SOCKS', qty: 2 },
+    { sku: 'TEE', qty: 2 },
+    { sku: 'BAG', qty: 1 }
+  ],
+  redeems: [
+    { card_id: 'GC-100', amount_cents: 3000 },
+    { card_id: 'GC-200', amount_cents: 1200 },
+    { card_id: 'GC-100', amount_cents: 500 }
+  ]
+}));
+
+const proc = spawnSync('node', ['bin/cli.js', 'gift-card', '--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), {
+  order_id: 'order-27',
+  subtotal_cents: 12100,
+  gift_card_applied_cents: 4700,
+  amount_due_cents: 7400,
+  items: [
+    { sku: 'TEE', qty: 3, line_cents: 7500 },
+    { sku: 'SOCKS', qty: 2, line_cents: 1400 },
+    { sku: 'BAG', qty: 1, line_cents: 3200 }
+  ],
+  redemptions: [
+    { card_id: 'GC-100', applied_cents: 3500, remaining_balance_cents: 1500 },
+    { card_id: 'GC-200', applied_cents: 1200, remaining_balance_cents: 1300 }
+  ]
+});
+
+process.stdout.write(JSON.stringify({ ok: true }) + '\n');