Spec files in your repository

specsgraph/
  README.md                 index of the model, generated
  glossary.md               every term with its definition
  actors.md                 people, systems and agents
  graph.json                machine-readable graph for tools and CI
  contexts/
    orders/
      context.md            purpose, subdomain, services, relationships
      requirements/
        ORD-12.md           one file per requirement, scenarios included
        ORD-13.md
  decisions/
    0007-reserve-stock-before-payment.md
  workstreams/
    WS-3.md

---
id: ORD-12
title: Reserve stock for every line item at checkout
context: orders
service: checkout
state: active
terms: [reservation, customer, line-item]
actors: [customer]
related: [BIL-04]
decisions: ["0007"]
---

# ORD-12 Reserve stock for every line item at checkout

When a Customer starts checkout, the system creates a reservation for the
full quantity of every line item before payment is requested.

## Scenarios

```gherkin
@ORD-12
Feature: Reserve stock for every line item at checkout

  Background:
    Given the Catalog has 5 units of "Trail mug" in stock
    And the Catalog has 1 unit of "Canvas tote" in stock

  Scenario: Every line item gets a reservation
    Given a Customer has a cart with 2 "Trail mug" and 1 "Canvas tote"
    When the Customer starts checkout
    Then a reservation holds 2 "Trail mug" for the order
    And a reservation holds 1 "Canvas tote" for the order
    And the Catalog shows 3 units of "Trail mug" available

  Scenario: Checkout stops when a line item cannot be reserved
    Given a Customer has a cart with 2 "Canvas tote"
    When the Customer starts checkout
    Then no reservation is created for the order
    And the Customer is told that only 1 "Canvas tote" is left
    And payment is not requested
```

## Links

- Term: [Reservation](../../../glossary.md#reservation)
- Actor: [Customer](../../../actors.md#customer)
- Requirement: [BIL-04](../../billing/requirements/BIL-04.md) Capture payment only once stock is reserved
- Decision: [0007 Reserve stock before payment](../../../decisions/0007-reserve-stock-before-payment.md)

{
  "schemaVersion": 1,
  "project": { "key": "shop", "name": "Shop" },
  "contexts": [
    { "key": "ORD", "slug": "orders", "name": "Orders", "subdomain": "core", "owner": "Checkout team" },
    { "key": "BIL", "slug": "billing", "name": "Billing", "subdomain": "supporting", "owner": "Billing team" }
  ],
  "relationships": [
    { "upstream": "CAT", "downstream": "ORD", "patterns": ["customer-supplier"] },
    { "upstream": "ORD", "downstream": "BIL", "patterns": ["partnership"] }
  ],
  "requirements": [
    {
      "id": "ORD-12",
      "title": "Reserve stock for every line item at checkout",
      "context": "ORD",
      "state": "active",
      "file": "contexts/orders/requirements/ORD-12.md",
      "scenarios": 2,
      "related": ["BIL-04"],
      "decisions": ["0007"]
    }
  ]
}

---
key: ORD
slug: orders
name: Orders
subdomain: core
owner: Checkout team
services: [checkout, order-history]
upstream:
  - { context: CAT, patterns: [customer-supplier] }
  - { context: IDN, patterns: [open-host-service] }
downstream:
  - { context: BIL, patterns: [partnership] }
  - { context: FUL, patterns: [published-language] }
  - { context: ANL, patterns: [published-language] }
---

# Orders

Turns a cart into a confirmed order and holds stock while the Customer pays.
Does not ship anything.

name: Requirement IDs

on:
  pull_request:
    types: [opened, edited, synchronize, labeled, unlabeled]

jobs:
  cite-requirements:
    if: ${{ !startsWith(github.head_ref, 'spec/') && !contains(github.event.pull_request.labels.*.name, 'no-spec') }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Check cited requirement IDs
        env:
          PR_TEXT: ${{ github.event.pull_request.title }} ${{ github.event.pull_request.body }}
        run: |
          keys=$(jq -r '.contexts[].key' specsgraph/graph.json | paste -sd '|' -)
          ids=$(printf '%s' "$PR_TEXT" | grep -oE "\b($keys)-[0-9]+\b" | sort -u)
          if [ -z "$ids" ]; then
            echo "Cite at least one requirement ID, for example ORD-12."
            exit 1
          fi
          for id in $ids; do
            jq -e --arg id "$id" '.requirements[] | select(.id == $id)' specsgraph/graph.json > /dev/null \
              || { echo "Unknown requirement ID: $id"; exit 1; }
          done

name: Spec folder

on:
  pull_request:
    paths:
      - "specsgraph/**"

jobs:
  generated-only:
    if: ${{ !startsWith(github.head_ref, 'spec/') }}
    runs-on: ubuntu-latest
    steps:
      - run: |
          echo "Files in specsgraph/ are generated by SpecsGraph. Propose the change there instead."
          exit 1

mkdir -p features
for f in specsgraph/contexts/*/requirements/*.md; do
  grep -q '^state: retired' "$f" && continue
  awk '/^```gherkin$/ { on = 1; next } /^```$/ { on = 0 } on' "$f" \
    > "features/$(basename "$f" .md).feature"
done

# Run the scenarios of one requirement, next to your step definitions
npx cucumber-js features --tags "@ORD-12"