Your agents rewrite the code. Your customers shouldn’t notice.

The life of one promise

A checkout service promises that a customer who pays sees a confirmation and gets one receipt. Here is that promise, from the line someone writes to the review that lets a change to it through.

1. 1

   Someone writes it down

   An outcome is a sentence about a person or system outside yours: a customer, an external caller, data you own, an obligation. It names the intent it serves, the request that sets it off and what has to be true afterwards.

   It lives in oodlc/, a plain folder of YAML at the root of the repo. Give the folder a CODEOWNERS entry and changes to it reach the people who should see them.

   outcomes:
     - id: checkout.payment-confirmed
       intent: buy-without-surprises
       statement: After a successful payment the customer
         sees a confirmation and gets exactly one receipt
       boundary: customer
       trigger:
         http: POST /checkout
       conditions: [first_purchase, payment_provider_slow,
                    security.no-credentials]
       expect:
         status: 200
         body:
           order_id: { exists: true }
           status: confirmed
         effects:
           - { kind: email.sent, match: { template: receipt }, count: 1 }
         latency_ms_max: 2000
       when:
         security.no-credentials:
           status: 401
           effects: [{ kind: payment.capture, count: 0 }]
   

2. 2

   Oodle runs it somewhere sealed

   Oodle starts your app in process, with no port open, and tries each outcome under each condition it lists: a first purchase, a slow payment provider, a request with no credentials.

   Calls to Stripe or SendGrid are answered by stubs and recorded, so the outcome can say “exactly one receipt” and mean it. A call to a host nobody named doesn't leave the process; it fails the run. If the service keeps its data in Postgres, a real one runs in the same process, reset before every run. The clock, uuids and random numbers are fixed, so the same code gives the same answer twice.

   app: src/app.ts
   defaults:
     given:
       state: { customers: [{ id: c1, email: ada@example.com }] }
       stubs:
         payment.capture:
           result: { id: pay_1, status: succeeded }
           latency_ms: 120
   

3. 3

   Every pull request gets a diff of promises

   On each pull request Oodle runs the base branch and the change, then sorts every outcome into one of eight piles. The comment lists them, and the check fails only if something blocks.

   Things the system does that nobody promised, like an internal audit event or a health endpoint, are behaviors. When they drift, the comment says so in its own section and the check stays green.

   Status	Means	Blocks the merge
   held	Passes, and the customer sees exactly what they saw before.	No
   changed	Still passes, but what the customer sees is different.	Until approved
   broken	Passed on the base branch, fails on this one.	Yes, and can't be approved
   failing	Fails here and was already failing before.	Yes
   new	The base branch didn't promise this yet. It passes.	No
   removed	Taken out of the catalog.	Until approved
   redefined	Its definition in the catalog was edited.	Until approved
   proposed	Drafted, usually by an agent. Runs and reports.	No

4. 4

   A person approves the change they meant

   When a change to a promise is on purpose, the comment ends with the line that approves it. A maintainer other than the author puts that line in a review, and the check runs again green with their name on it.

   The approval covers that change as it stands. Push something that changes the output again and it needs approving again. A broken outcome never gets an approve line.

   /oodle approve checkout.payment-confirmed@1a2b3c4d
   
   # the comment, once the check has run again
   🟡 changed ✅ approved by @mara  checkout.payment-confirmed
      customer · [default] body.currency added