Stage 0 / 10 min

Stage 0: Ground the work

Frame the boundary before an agent acts.

Your orientation Stage 0 · Define / PlanIntuition · Common language · Habit

Where you are in the work

Define / Plan
Execute
Judge
Learn

What you are developing

Intuition

Recognize why local success cannot prove a service boundary.

Build this understanding

Common language / Standardization

Name the context boundary and authority order.

Use the shared language

Habit / Behavior

Record a prediction before investigating.

Practice this behavior

Intuition

STAGE 0 · GROUND THE WORKFrame the Boundary10 min

Concept — context boundary and authority

You leave with — a sealed prediction, and knowing which document wins an argument

Before an agent does anything, two questions have to be settled: what is it allowed to see, and when two documents disagree, which one wins? Skip these and every later decision inherits the ambiguity.

1 · Start the lab

⌘  /lab

Then confirm a journey event actually landed in .claude/journey/ — not merely that the command returned. A silent journey failure surfaces at Stage 6, which is far too late to fix it.

2 · Read the boundary

Open docs/SCENARIO_GROUNDING.md.

flowchart LR
  accTitle: The complete service flow
  accDescr: WSAPI to TTA to Payment Processor to CPC to Injection to LCS to DCF. TTA and Payment Processor: you work here. Downstream services: not implemented in this lab.
  W("WSAPI") --> T
  subgraph lab["you work here"]
    T("TTA"):::focus --> P("Payment Processor"):::focus
  end
  P --> C
  subgraph downstream["not implemented in this lab"]
    C("CPC") --> I("Injection") --> L("LCS") --> D("DCF")
  end

That document also separates three things you must keep apart all session: what is grounded Meridian behaviour, what is lab simplification, and what is a deliberately planted defect. The planted ones are teaching fixtures. They do not imply anything about real Meridian systems.

Read the boundary · Scenario grounding

Scenario grounding — what is real, what is simplified, what is planted

This lab sits in the Meridian refund domain and uses real Meridian terminology. That makes it worth being exact about which parts are grounded behaviour, which are simplifications made so the exercise fits in two hours, and which are deliberate teaching fixtures.

The rule the lab authors worked to: inventing lab code is acceptable; inventing Meridian platform behaviour is not. A failure mechanism may be simulated. The engineering principle it demonstrates may not be made up.

The three layers

Layer 1 — Meridian fact

Behaviour supported by the supplied Meridian material, recorded decision by decision in PGS_DECISIONS.md with its citation.

Examples: the wider refund flow and where TTA and Payment Processor sit in it; the request field mapping; the two refund endpoints and the identifiers that select between them; the status codes, including 409 for a duplicate; refunds not exceeding the captured amount, per order and per capture; idempotency being required on money-moving paths; correlation IDs propagating end to end; Void being out of scope; settlement being downstream.

Layer 2 — Lab representation

Deliberate simplifications, each labelled as such in PGS_DECISIONS.md.

Examples: two editable repositories; only the TTA → Payment Processor seam being executable; online/offline supplied as an input rather than modelling CPC’s decision; in-memory stores instead of Oracle; a deterministic authorization stub with no network; the contract version numbers; the specific transport field carrying the retry identity; the correlation header name; a local compatibility harness standing in for a deployment pipeline.

Layer 3 — Seeded failure

Defects introduced deliberately by the lab authors to create the exercise.

Their presence does not imply that the same defect exists, or ever existed, in a Meridian production system. They are teaching fixtures. What is grounded is the principle each one demonstrates and the behaviour that correcting it restores.

This document does not say where they are. Finding them is the work.

What the lab deliberately does not model

CPC behaviour beyond the state supplied at the seam · refund injection · LCS API · DCF generation and the settlement lifecycle · ISO 8583 and DE48 mapping · A3RS, BECS, BPSS and surrounding platform components · production routing, regional and blue-green topology · the production CI/CD, integration-environment and release-governance path · the real team-ownership and merge-approval model across repositories · merchant-privilege enforcement.

These are scope reductions for the exercise. They are not architectural claims. Nothing here says the real system lacks them.

What “success” means, precisely

The represented TTA → Payment Processor slice is internally consistent, contract-compatible, tested, and independently validated against the supplied technical authority.

That is narrower than “the refund capability works”. The lab proves the represented seam locally. It does not claim the wider Meridian refund capability is production-ready, and pair verification does not replace Meridian integration testing or release governance.

Why the grounding discipline is the point, not the paperwork

The habit this lab is trying to build is the one that matters when the AI is confident and the source is silent. An agent asked to finish a refund path will produce something plausible for a threshold nobody specified, an endpoint nobody published, or a dependency nobody built. It will read well. In payments it will also be a business decision made by something with no authority to make it.

Separating fact from representation from fixture — here, and in your own work — is what makes that difference visible before it ships.

Download the unchanged original source

Common language / Standardization

3 · Note the authority order

flowchart TB
  accTitle: Source authority order
  accDescr: Highest authority first. Preserve exclusions and the distinction between fact, lab representation, and what is not modelled. Build only once the specification is READY.
  N["specs/NON_NEGOTIABLES.md / highest. Holds regardless of anything else."] --> O["specs/OUT_OF_SCOPE.md / what must not be built"]
  O --> D["docs/PGS_DECISIONS.md / fact vs. lab representation vs. not modelled"]
  D --> S["specs/refund-seam-phase1.spec.md / what to build, once it is READY"]

Higher wins. The top three are write-protected — try to edit one and the write gate stops you. That is deliberate: a lab whose rules can be edited by the thing being graded is not measuring anything.

Habit / Behavior

4 · ◆ Predict #1 — seal this now

Two repositories have to end up agreeing. Which side should change first, and why?

Write it in your notes, with your reasoning, before you look at a single line of code.

You will reopen this twice — once when you understand the seam, and once when you have hard evidence. Do not go researching it now. A prediction you have already looked up teaches you nothing.

5 · Close the stage

⌘  /hand-off

Carry the work forward

Complete the stage’s instructions and hand-off above before continuing. Keep your evidence and unresolved questions with the work.

If you fall behind or need help