@adammcarter/use-cases 0.1.0

package/docs/showcase.md

@@ -0,0 +1,39 @@
+# Showcases
+
+A showcase is a live run in front of the user or another reviewer. The agent can
+drive the run, the user can drive it, or a script can drive it, depending on the
+use case and user preference.
+
+The mechanical flow is:
+
+```text
+start -> item -> observation -> verdict -> continue
+                  |
+                  +-> fail -> continue | pause_to_fix | waive_with_reason | abort
+finish -> approval when required
+```
+
+Use `plan showcase` for a short, high-value demo and `plan walkthrough` for
+broader coverage. Use `capsule plan` when a persisted smoke demo or golden path
+script already exists. A generated plan is prepared material until
+`showcase start --plan-file` records a run against its content hash.
+
+Use `capsule run --capsule <id>` when the persisted capsule should be performed
+now. Instruction steps become action events. Static observation steps are
+recorded as prompts for a real runtime observation; they do not become proof and
+do not create pass verdicts by themselves. Command-backed observations can
+record pass/fail verdicts in the same append-only showcase ledger. Successful
+command-backed runs are finished automatically; runs with pending runtime
+observations or failed commands stay open so the agent or user can continue,
+pause to fix, waive with a reason, or abort.
+
+Command steps are inert by default. They run only when the caller passes
+`--execute-commands` and the capsule sets `permissions.command_execution: true`.
+The runner executes an exact executable/argv pair without a shell, requires the
+working directory to stay inside the repository, uses a small environment
+allowlist, and records bounded/redacted stdout/stderr plus the exit code as the
+observation.
+
+User-required approval cannot be recorded by an agent or MCP tool. The trusted
+path is the interactive CLI-mediated user approval command. Approval is only
+valid after finish, and is bound to the plan hash and finish event.

package/docs/tutorials/python-pytest.md

@@ -0,0 +1,188 @@
+# Tutorial: adopt the matrix in a pure-Python repo (pytest, no JS)
+
+This walkthrough proves the headline claim — **anyone can adopt Use Cases,
+not just JavaScript repos** — by taking a tiny Python project from nothing to a
+signed **FRESH** row using a **pure Python toolchain**. There is **no pnpm and no
+vitest** anywhere in the project: the verifier is `pytest`.
+
+The complete, runnable project lives at
+[`examples/python-pytest/`](../../examples/python-pytest), and it is exercised
+end-to-end (from the published `uc` tarball, running real `pytest`) by
+[`tests/release/example-python-pytest.test.ts`](../../tests/release/example-python-pytest.test.ts).
+
+> The only Node you install is the `uc` CLI itself (the trust engine). The code
+> under test, the acceptance test, and the verifier are 100% Python.
+
+---
+
+## What the project looks like
+
+```
+examples/python-pytest/
+├─ use-cases.yml                       # workspace config: acceptance → python.pytest preset
+├─ pytest.ini                                     # importlib mode + pythonpath=src
+├─ src/coupon.py                                  # implementation, wrapped in a marker block
+├─ tests/use_cases/
+│  └─ example.checkout.apply_coupon_test.py       # acceptance test the preset runs
+└─ use-cases/checkout.yml                         # the matrix row
+```
+
+### The workspace config (`use-cases.yml`)
+
+The `acceptance` verifier resolves to the **`python.pytest` preset** — the same
+config-driven verifier model JS repos use, just pointed at pytest:
+
+```yaml
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: python.pytest      # runs: pytest tests/use_cases/{slug}_test.py
+    evidence_kind: test_result
+```
+
+### The marked code (`src/coupon.py`)
+
+`#` is the configured comment prefix for `.py`, so the marker is the Python
+spelling of the same `<comment>: @use-case: <slug>` convention:
+
+```python
+#: @use-case: example.checkout.apply_coupon
+COUPONS = {"SAVE10": 10, "HALF": 50}
+
+
+def apply_coupon(subtotal_cents: int, code: str) -> int:
+    if subtotal_cents <= 0:
+        raise ValueError("subtotal must be positive")
+    if code not in COUPONS:
+        raise KeyError(f"unknown coupon: {code}")
+    discount = subtotal_cents * COUPONS[code] // 100
+    return subtotal_cents - discount
+#: @use-case: end example.checkout.apply_coupon
+```
+
+### The acceptance test
+
+The `python.pytest` preset derives the path `tests/use_cases/{slug}_test.py` from
+the row id, so the test file is
+`tests/use_cases/example.checkout.apply_coupon_test.py`:
+
+```python
+from coupon import apply_coupon
+
+def test_percentage_coupon_discounts_the_subtotal():
+    assert apply_coupon(1000, "SAVE10") == 900
+```
+
+`pytest.ini` makes that path collectable and importable with **no packaging
+boilerplate**:
+
+```ini
+[pytest]
+# importlib mode lets pytest collect the dotted row-id filename;
+# pythonpath=src lets the test `from coupon import ...`.
+addopts = --import-mode=importlib
+pythonpath = src
+```
+
+---
+
+## The flow: from nothing to FRESH
+
+Install the CLI once (the only Node dependency), then drive the trust flow. These
+are the exact commands the release test runs.
+
+### 0. Install the CLI and generate a scratch signing key
+
+```bash
+npm i -g use-cases                  # provides the `uc` binary
+# A throwaway ed25519 keypair. In production the PRIVATE key lives ONLY in CI.
+node -e 'const c=require("crypto"),f=require("fs");const k=c.generateKeyPairSync("ed25519");
+f.writeFileSync("public-key.pem",k.publicKey.export({type:"spki",format:"pem"}));
+f.writeFileSync("private-key.pem",k.privateKey.export({type:"pkcs8",format:"pem"}));'
+```
+
+### 1. Validate the matrix
+
+```bash
+uc matrix validate --repo . --json     # ok: true
+```
+
+### 2. Register the binding
+
+The marker already lives in `src/coupon.py`, so register it without editing
+source:
+
+```bash
+uc bind --repo . \
+  --row example.checkout.apply_coupon \
+  --file src/coupon.py \
+  --mode explicit --register-existing --json
+```
+
+### 3. Scan — the row is UNPROVEN
+
+```bash
+uc scan --repo . --public-key public-key.pem --json
+# example.checkout.apply_coupon → UNPROVEN  (bound, but no signed proof yet)
+```
+
+### 4. Verify — runs REAL pytest (keyless)
+
+`verify` resolves the `python.pytest` preset and actually runs
+`pytest tests/use_cases/example.checkout.apply_coupon_test.py`. It holds **no
+signing key** and writes an unsigned results ledger:
+
+```bash
+uc verify --repo . --all --out verification-results.jsonl \
+  --public-key public-key.pem --json
+# results[0].status: "pass", verifier_id: "acceptance", exit_code: 0
+```
+
+### 5. Prove — sign from the verification result (trusted CI)
+
+`prove` consumes the unsigned results, recomputes every hash itself, and mints an
+ed25519-signed proof. Locally you can use the scratch key; in production the key
+is a CI secret:
+
+```bash
+UCM_SIGNING_KEY="$(cat private-key.pem)" \
+uc prove --repo . --all --trusted-ci --append \
+  --verification-results verification-results.jsonl \
+  --signing-key-env UCM_SIGNING_KEY \
+  --public-key public-key.pem --json
+# rows[0].status: "signed", proof_events_appended: 1
+```
+
+### 6. Scan again — the row is FRESH
+
+```bash
+uc scan --repo . --public-key public-key.pem --json
+# summary: { fresh: 1, ... }   example.checkout.apply_coupon → FRESH
+```
+
+---
+
+## Why this is honest, not a rubber stamp
+
+Break the production code so the genuine acceptance test fails, then re-verify:
+
+```bash
+# drop the discount in src/coupon.py, then:
+uc verify --repo . --all --out verification-results.jsonl --public-key public-key.pem --json
+# results[0].status: "fail", exit_code != 0
+```
+
+`prove` now refuses (`reason: RESULT_FAILED`, nothing appended) and the row stays
+out of FRESH. The proof is bound to a verifier that **really ran** — exactly the
+guarantee the JS path gives, delivered by a pure-Python toolchain.
+
+| Stage | Command | Row state |
+|---|---|---|
+| Authored | `uc matrix validate` | (tracked) |
+| Bound | `uc bind … --register-existing` | UNPROVEN |
+| Verified (keyless, real pytest) | `uc verify --out …` | UNPROVEN (results only) |
+| Proved (trusted, signed) | `uc prove --trusted-ci …` | **FRESH** |
+| Production code broken | `uc verify` → `uc prove` | refused → not FRESH |
+
+See [verifiers](../concepts/verifiers.md) for the full preset model and
+[getting started](../getting-started.md) for the JS path and the CI workflow.

package/examples/basic-product/demo-capsules/product-search.yml

@@ -0,0 +1,23 @@
+schema_version: 1
+capsule_id: capsule.basic.product_search
+title: Product search showcase
+mode: showcase
+description: Demonstrate the golden product search path.
+audience: reviewer
+timebox_seconds: 600
+items:
+  - use_case_id: product.search.golden
+    scenario_ids: [product.search.golden.cli]
+    runbook:
+      - kind: instruction
+        text: Open the product search surface.
+      - kind: instruction
+        text: Search for a known product.
+      - kind: observation
+        text: Confirm that matching results and a selectable product are visible.
+permissions:
+  command_execution: false
+extensions:
+  use-cases.dev/runner:
+    command: uc capsule run --repo examples/basic-product --capsule capsule.basic.product_search --json
+    command_steps: none

package/examples/basic-product/evidence/by-id/ev/evidence-basic-search.jsonl

@@ -0,0 +1 @@
+{"schema_version":1,"event_type":"evidence_recorded","event_id":"evt_basic_search_evidence_1","aggregate_id":"evidence.basic.search.1","sequence":1,"recorded_at":"2026-06-25T00:00:00.000Z","actor_type":"script","host_surface":"codex.cli","idempotency_key":"example:basic:evidence:search","payload":{"targets":[{"use_case_id":"product.search.golden","use_case_semantic_hash":"sha256:3331f31a3c86b251cf9a2783a06291d7277ab475753c79a709ef1691ac72f701"}],"kind":"test_result","captured_at":"2026-06-25T00:00:00.000Z","result":"pass","summary":"Example product search check passed.","producer":{"type":"script"},"method":{"type":"structured_command","executable":"pnpm","argv":["test","product-search"]},"evidence_kind":"test_result","use_case_ids":["product.search.golden"],"verifier":{"type":"script"},"verdict":"pass"}}

package/examples/basic-product/showcase-runs/run.basic.product.search/events.jsonl

@@ -0,0 +1,4 @@
+{"schema_version":1,"event_type":"run_started","event_id":"evt_basic_showcase_start","run_id":"run.basic.product.search","aggregate_id":"run.basic.product.search","sequence":1,"recorded_at":"2026-06-25T00:00:00.000Z","actor_type":"agent","host_surface":"codex.cli","idempotency_key":"example:basic:showcase:start","intent_digest":"sha256:1111111111111111111111111111111111111111111111111111111111111111","payload":{"plan":{"schema_version":1,"plan_id":"plan.basic.product.search","mode":"showcase","complete":true,"selected_items":[{"plan_item_id":"item.product.search.golden","use_case_id":"product.search.golden","scenario_ids":["product.search.golden.cli"],"verification_policy_snapshot":{"mode":"requirements","requirements":[{"evidence_kind":"test_result","required_verifiers":["script"],"minimum_count":1}]},"approval_policy_snapshot":{"mode":"predefined","requirements":[{"approver_type":"user","minimum_count":1}],"statement":"User approval follows the live product search showcase."}}],"known_gaps":[]},"control_mode":"agent_led","initial_epoch_id":"epoch.1","known_gap_acknowledgement":null}}
+{"schema_version":1,"event_type":"observation_recorded","event_id":"evt_basic_showcase_observation","run_id":"run.basic.product.search","aggregate_id":"run.basic.product.search","sequence":2,"recorded_at":"2026-06-25T00:01:00.000Z","actor_type":"agent","host_surface":"codex.cli","idempotency_key":"example:basic:showcase:observation","intent_digest":"sha256:2222222222222222222222222222222222222222222222222222222222222222","payload":{"plan_item_id":"item.product.search.golden","epoch_id":"epoch.1","observation":"The product search result appeared in the live demo."}}
+{"schema_version":1,"event_type":"verdict_recorded","event_id":"evt_basic_showcase_verdict","run_id":"run.basic.product.search","aggregate_id":"run.basic.product.search","sequence":3,"recorded_at":"2026-06-25T00:02:00.000Z","actor_type":"user","host_surface":"codex.cli","idempotency_key":"example:basic:showcase:verdict","intent_digest":"sha256:3333333333333333333333333333333333333333333333333333333333333333","payload":{"plan_item_id":"item.product.search.golden","epoch_id":"epoch.1","observation_event_ids":["evt_basic_showcase_observation"],"verdict":"pass","verifier":{"type":"user"}}}
+{"schema_version":1,"event_type":"run_finished","event_id":"evt_basic_showcase_finish","run_id":"run.basic.product.search","aggregate_id":"run.basic.product.search","sequence":4,"recorded_at":"2026-06-25T00:03:00.000Z","actor_type":"agent","host_surface":"codex.cli","idempotency_key":"example:basic:showcase:finish","intent_digest":"sha256:4444444444444444444444444444444444444444444444444444444444444444","payload":{"requested_finish":true}}

package/examples/basic-product/use-cases/product.yml

@@ -0,0 +1,85 @@
+schema_version: 1
+feature:
+  id: product.search
+  name: Product search
+  summary: Users can find and refine product results.
+metadata:
+  owner: use-cases
+  lifecycle: active
+use_cases:
+  - id: product.search.golden
+    title: Find a product from the main search box
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags: [product, search, showcase]
+    source_refs:
+      - kind: file
+        path: src/product/search.ts
+    actor: shopper
+    intent: Find a matching product quickly.
+    preconditions:
+      - Product catalog contains visible items.
+    trigger: Shopper submits a product search.
+    scenarios:
+      - id: product.search.golden.cli
+        kind: steps
+        steps:
+          - Open the product search surface.
+          - Search for a known product.
+          - Select the highest-ranked matching result.
+    observable_outcomes:
+      - Matching product results are visible.
+      - The selected product can be opened from the results list.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+      - host_surface: opencode.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers: [script]
+          minimum_count: 1
+    approval_policy:
+      mode: predefined
+      requirements:
+        - approver_type: user
+          minimum_count: 1
+      statement: User approval follows the live product search showcase.
+  - id: product.filter.alternate
+    title: Refine product results with a filter
+    lifecycle: active
+    value_tier: core
+    journey_role: alternate
+    usage_frequency: occasional
+    tags: [product, filter]
+    source_refs:
+      - kind: file
+        path: src/product/filter.ts
+    actor: shopper
+    intent: Narrow a product result set.
+    preconditions:
+      - Product search results are visible.
+    trigger: Shopper applies a category filter.
+    scenarios:
+      - id: product.filter.alternate.cli
+        kind: steps
+        steps:
+          - Search for a product category.
+          - Apply one category filter.
+    observable_outcomes:
+      - Results are narrowed to the selected category.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/examples/basic-product/use-cases.yml

@@ -0,0 +1,9 @@
+schema_version: 1
+workspace_id: basic-product-example
+component_id: basic-product
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous

package/examples/damaged-product/evidence/broken.jsonl

@@ -0,0 +1 @@
+{"schema_version":1,"event_type":"evidence_recorded","event_id":"evt_bad_json"

package/examples/damaged-product/use-cases/duplicate-a.yml

@@ -0,0 +1,28 @@
+schema_version: 1
+feature:
+  id: damage.duplicate
+  name: Duplicate use cases
+  summary: Duplicate IDs are ambiguous.
+use_cases:
+  - id: damage.duplicate.id
+    title: Duplicate use case A
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    actor: agent
+    intent: Exercise duplicate detection.
+    preconditions: [A duplicate sibling exists.]
+    trigger: Matrix validation runs.
+    scenarios:
+      - id: damage.duplicate.a.cli
+        kind: steps
+        steps: [Validate duplicate A.]
+    observable_outcomes: [Duplicate A is marked ambiguous.]
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/examples/damaged-product/use-cases/duplicate-b.yml

@@ -0,0 +1,28 @@
+schema_version: 1
+feature:
+  id: damage.duplicate
+  name: Duplicate use cases
+  summary: Duplicate IDs are ambiguous.
+use_cases:
+  - id: damage.duplicate.id
+    title: Duplicate use case B
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    actor: agent
+    intent: Exercise duplicate detection.
+    preconditions: [A duplicate sibling exists.]
+    trigger: Matrix validation runs.
+    scenarios:
+      - id: damage.duplicate.b.cli
+        kind: steps
+        steps: [Validate duplicate B.]
+    observable_outcomes: [Duplicate B is marked ambiguous.]
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/examples/damaged-product/use-cases/malformed.yml

@@ -0,0 +1,14 @@
+schema_version: 1
+feature:
+  id: damage.malformed
+  name: Malformed file
+  summary: This file is intentionally malformed.
+use_cases:
+  - id: damage.malformed
+    title: Broken
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    actor: agent
+    intent: [

package/examples/damaged-product/use-cases/valid-sibling.yml

@@ -0,0 +1,28 @@
+schema_version: 1
+feature:
+  id: damage.valid
+  name: Damaged fixture valid sibling
+  summary: A valid sibling remains usable while nearby files are damaged.
+use_cases:
+  - id: damage.valid.sibling
+    title: Valid sibling remains addressable
+    lifecycle: active
+    value_tier: supporting
+    journey_role: edge
+    usage_frequency: rare
+    actor: agent
+    intent: Confirm partial matrix recovery.
+    preconditions: [At least one nearby file is damaged.]
+    trigger: Matrix validation runs.
+    scenarios:
+      - id: damage.valid.sibling.cli
+        kind: steps
+        steps: [Validate the damaged workspace.]
+    observable_outcomes: [The valid sibling is still addressable.]
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+    verification_policy:
+      mode: none
+    approval_policy:
+      mode: none

package/examples/damaged-product/use-cases.yml

@@ -0,0 +1,9 @@
+schema_version: 1
+workspace_id: damaged-product-example
+component_id: damaged-product
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous

package/examples/host-projections/use-cases.yml

@@ -0,0 +1,9 @@
+schema_version: 1
+workspace_id: host-projections-example
+component_id: host-projections-example
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous

package/examples/python-pytest/README.md

@@ -0,0 +1,39 @@
+# Example: Python + pytest
+
+A minimal, already-wired Use Cases workspace that proves the headline
+trust flow against real pytest tests. It mirrors the full walkthrough in
+[`docs/tutorials/python-pytest.md`](../../docs/tutorials/python-pytest.md) — read
+that for the step-by-step narrative; this README is the map.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `use-cases.yml` | Workspace config. `verifiers.default` runs pytest. |
+| `use-cases/checkout.yml` | One behaviour row: `example.checkout.apply_coupon`. |
+| `src/coupon.py` | The code that satisfies the row, wrapped in `//: @use-case:` markers (Python uses `#:` comment prefix). |
+| `tests/use_cases/…_test.py` | The pytest test that verifies the behaviour. |
+
+Because the code is already marked, adopt it with `bind --register-existing`
+(register the existing span) rather than a fresh `bind` (which would insert new
+markers).
+
+## Run it
+
+```bash
+# from this directory, with `use-cases` installed (npm i -g use-cases)
+uc matrix validate --repo .            # matrix is clean
+uc scan --repo .                       # row is UNBOUND until you register it
+
+# register the already-marked span, then run the trust flow:
+uc bind --row example.checkout.apply_coupon \
+  --file src/coupon.py --register-existing
+uc verify --all --out verify-results.jsonl --repo .        # runs pytest
+# prove needs an ed25519 signing key — see docs/security/key-management.md:
+#   node -e '...generateKeyPairSync("ed25519")...'  (one-liner in that doc)
+uc prove --all --trusted-ci --signing-key-env UCM_CI_SIGNING_KEY \
+  --verification-results verify-results.jsonl --append --repo .
+uc scan --repo . --public-key ci-signing-key.pub.pem      # row reads FRESH
+
+# now edit src/coupon.py inside the marked span and re-scan — it flips to SUSPECT.
+```

package/examples/python-pytest/pytest.ini

@@ -0,0 +1,8 @@
+[pytest]
+# `--import-mode=importlib` lets pytest collect the acceptance test whose filename
+# carries the dotted row id (example.checkout.apply_coupon_test.py); the default
+# "prepend" import mode rejects dots in module names.
+# `pythonpath = src` puts the implementation module (coupon.py) on sys.path so the
+# test can `from coupon import apply_coupon` without any packaging boilerplate.
+addopts = --import-mode=importlib
+pythonpath = src

package/examples/python-pytest/src/coupon.py

@@ -0,0 +1,32 @@
+"""A tiny, self-contained checkout helper an adopter might own.
+
+The function below is the implementation the use-case row
+`example.checkout.apply_coupon` describes. It is wrapped in a Use Cases
+marker block (the `@use-case` start/end comments below) so the matrix can bind
+the row to exactly these source lines.
+
+`#` is the configured comment prefix for `.py`, so the markers are the Python
+spelling of the same convention `//` languages use. No JavaScript, pnpm, or
+vitest is involved anywhere in this project.
+"""
+
+#: @use-case: example.checkout.apply_coupon
+COUPONS = {
+    "SAVE10": 10,  # 10% off
+    "HALF": 50,  # 50% off
+}
+
+
+def apply_coupon(subtotal_cents: int, code: str) -> int:
+    """Return the cart total in cents after applying coupon ``code``.
+
+    Raises ``ValueError`` for a non-positive subtotal and ``KeyError`` for an
+    unknown coupon code.
+    """
+    if subtotal_cents <= 0:
+        raise ValueError("subtotal must be positive")
+    if code not in COUPONS:
+        raise KeyError(f"unknown coupon: {code}")
+    discount = subtotal_cents * COUPONS[code] // 100
+    return subtotal_cents - discount
+#: @use-case: end example.checkout.apply_coupon

package/examples/python-pytest/tests/use_cases/example.checkout.apply_coupon_test.py

@@ -0,0 +1,31 @@
+"""Acceptance test for the `example.checkout.apply_coupon` use-case row.
+
+This is a plain pytest module — the `python.pytest` verifier preset runs it with
+
+    pytest tests/use_cases/example.checkout.apply_coupon_test.py
+
+(the path the preset derives from the row id). It imports the implementation via
+the `pythonpath = src` setting in pytest.ini, so there is no JS toolchain here.
+"""
+
+import pytest
+
+from coupon import apply_coupon
+
+
+def test_percentage_coupon_discounts_the_subtotal():
+    assert apply_coupon(1000, "SAVE10") == 900
+
+
+def test_half_off_coupon():
+    assert apply_coupon(2000, "HALF") == 1000
+
+
+def test_unknown_coupon_is_rejected():
+    with pytest.raises(KeyError):
+        apply_coupon(1000, "NOPE")
+
+
+def test_non_positive_subtotal_is_rejected():
+    with pytest.raises(ValueError):
+        apply_coupon(0, "SAVE10")

package/examples/python-pytest/use-cases/checkout.yml

@@ -0,0 +1,47 @@
+schema_version: 1
+feature:
+  id: example.checkout
+  name: Checkout coupons
+  summary: Shoppers can apply a coupon code to reduce their cart total.
+metadata:
+  owner: example-team
+  lifecycle: active
+use_cases:
+  - id: example.checkout.apply_coupon
+    title: Apply a valid coupon to a cart
+    lifecycle: active
+    value_tier: critical
+    journey_role: golden
+    usage_frequency: common
+    tags: [checkout, coupon, python]
+    source_refs:
+      - kind: file
+        path: src/coupon.py
+    actor: shopper
+    intent: Reduce the cart total by applying a known coupon code.
+    preconditions:
+      - A cart with a positive subtotal exists.
+    trigger: The shopper submits a coupon code at checkout.
+    scenarios:
+      - id: example.checkout.apply_coupon.main
+        kind: steps
+        steps:
+          - The shopper enters a known coupon code.
+          - The system looks up the coupon's discount percentage.
+          - The system subtracts the discount from the subtotal.
+    observable_outcomes:
+      - The returned cart total reflects the coupon discount.
+      - An unknown coupon code is rejected rather than silently ignored.
+    host_applicability:
+      - host_surface: codex.cli
+        supported: true
+      - host_surface: claude.cli
+        supported: true
+    verification_policy:
+      mode: requirements
+      requirements:
+        - evidence_kind: test_result
+          required_verifiers: [acceptance]
+          minimum_count: 1
+    approval_policy:
+      mode: none

package/examples/python-pytest/use-cases.yml

@@ -0,0 +1,19 @@
+schema_version: 1
+workspace_id: example.python-pytest
+component_id: example.python-pytest
+data_root: .
+use_cases_dir: use-cases
+evidence_dir: evidence
+demo_capsules_dir: demo-capsules
+showcase_runs_dir: showcase-runs
+default_workflow_mode: continuous
+# Verifiers map a row's required_verifiers id to a real command. `default` is used
+# by any row that does not name its own verifier. This workspace adopts the matrix
+# with a PURE PYTHON toolchain: the `acceptance` verifier resolves to the
+# `python.pytest` preset, which runs `pytest tests/use_cases/<row-id>_test.py`.
+# There is no pnpm/vitest anywhere in this project.
+verifiers:
+  default: acceptance
+  acceptance:
+    preset: python.pytest
+    evidence_kind: test_result