usedesign.

02 — where the answer is scattered

Four genres that never agree

Four islands. Each knows one thing well and cannot be asked about anything else.

None of them is a catalogue of operations. And none of them lets an artifact — a test, a screen, a contract, a migration — declare what it implements and which stage of life it belongs to.

04 — prior art

We tried to buy this before building it

A description of an operation has to serve six consumers at once — the UI, the data model, the external contract, the service-to-service contract, the tests, and the database migrations. Here is how much of that six each existing family already covers.

Each family closes one or two of the six consumers. None of them closes the link between them.

05 — the gap

So what is actually missing?

06 — the idea

Describe it once. Let everything point back.

One operation, one file that both a human and a machine can read. Tests attach to steps. Screens declare which steps they cover. Migrations attach to the version axis. Nothing is left to be inferred.

The question “what proves this behaviour, and where is it shown to the user?” now has an answer that fits on one screen.

07 — structure

Three levels

Humans read the top. Tests and contracts attach to the bottom.

08 — the heart of the format

The axes of life

Stages of life are not a single field. Six different things change at six different speeds, and each is owned by different artifacts.

Squashing six clocks into one stage field is why traceability schemes rot. F arrived in round 7 — the format was published with five.

09 — the classic mistakes

Why the axes must never merge

10 — the file

Anatomy of a card

Deliberately boring: YAML front matter for machines, Markdown body for humans. No new language, no compiler, no runtime.

examples/library/
  library.loan.checkout.op.md

11 — fields

The fields that surprised us

Each one exists because writing real cards found somewhere the format had nothing to say.

12 — the payoff

Traceability, in both directions

steps:
  - id: s3-member-standing
    text: Member has no blocking holds — unpaid fines
          above the threshold, or a suspended card
    on_violation: { error: member_blocked, http: 403 }

tests:
  - { id: CheckoutTests.blocked_member_cannot_borrow,
      covers: s3-member-standing, level: integration }

interfaces:
  ui:
    screen: CirculationDesk
    covers_steps: [s1-copy-available, s3-member-standing,
                   s4-loan-limit, s5-commit]

coverage_gaps:
  - step: s6-audit
    gap: no test for the rollback path
         when the audit write fails

ui.covers_steps is the mechanism that makes UI/API drift visible: if a screen claims to cover a step that does not exist, the checker fails.

13 — example · the ordinary case

library.loan.checkout

A synchronous write: optimistic locking, a lifecycle transition, an audit trail, and a counterpart that undoes it. The shape everything else varies from.

- id: s3-member-standing
  text: Member has no blocking holds — unpaid fines
        above the threshold, or a suspended card
  on_violation: { error: member_blocked, http: 403 }
  rationale: >
    Checked before the loan limit so the member sees the
    real reason. Hitting the limit is recoverable by
    returning a book; a suspension is not …

- id: s4-loan-limit
  text: Member is below the concurrent loan limit for
        their membership tier
  on_violation: { error: loan_limit_reached, http: 409 }

14 — example · asynchronous work

library.catalog.import

The response means accepted, not done. Everything interesting happens afterwards, in a worker with a life of its own.

async_execution:
  job_states: [queued, running, succeeded, partial,
                failed, cancel_requested, cancelled]
  terminal: [succeeded, partial, failed, cancelled]
  worker: src/workers/ImportWorker.ts
  observe_via: GET /v1/imports/{jobId}
  s2s_dependency:
    service: MetadataEnrichment
    failure_mode: >
      Job ends as `partial`, not `failed` — titles are
      imported without authority links …

quota:
  scheme: per_credential_per_minute
  categories:
    import: { bucket: 5, window_min: 1 }
  applies_to: api_key_callers_only

interfaces:
  rpc:
    transport: json_rpc
    quota:
      categories: { write: { bucket: 2, window_min: 1 } }
      applies_to: all_rpc_callers

15 — example · irreversible, and its helper

library.member.purge

The card that justifies making reversibility a required field. Every other write here can be undone. This one cannot — and that single fact changes four things at once.

reversibility: irreversible

steps:
  - id: s2-closed
    text: Membership is already closed — an active
          member cannot be purged directly
    on_violation: { error: member_still_active, http: 409 }
    rationale: >
      Forcing closure first makes erasure a two-person,
      two-step act. A single call that both closes and
      erases would turn a misclick into an
      unrecoverable loss.

serves_step:
  operation: library.member.purge
  step: s3-settled
  purpose: >
    Let the operator see the obstacle before attempting
    an irreversible action, instead of discovering it as
    a rejection. The point is not to report the conflict
    afterwards — it is to prevent the attempt.

data_transition: null
provenance: none

17 — maturity of the spec itself

How this was hardened

v0.2 was reached by writing cards for eight real operations of a production system and recording where the format broke. Since then: twenty-nine more rounds, thirty-one in all, on three stacks, eight of them driven by a pilot on a product the format had never seen — and, on 13 September 2026, v1.0.

18 — where it stands

Where it stands — October 2026

Numbers read from the repositories and the registry, not from memory.

19 — elsewhere

Does it transfer? What broke, what still can

One foreign pilot, eleven issues — five in its first round, four in its second, two in between. Three more have followed (#12–#14); all fourteen are closed. Each was a real hole, not a matter of taste.

20 — technology

Boring on purpose

"$comment": "Claiming 'tested' or beyond requires at
least one recorded test and a tested note.",
"if": {
  "properties": {
    "maturity": { "enum": ["tested", "in_production"] }
  },
  "required": ["maturity"]
},
"then": {
  "properties": {
    "tests": { "minItems": 1 },
    "maturity_evidence": { "required": ["tested"] }
  },
  "required": ["tests"]
}

21 — architecture

How the pieces fit

An interactive map of the parts and of what each one compares with what — published next to this deck.

22 — where this goes

Roadmap