Skip to content
C.W.K.
Stream
Lesson 01 of 05 · published

A Stage Is Its Allowed Inputs

~12 min · contracts, architecture, pipelines, design

Level 0Wet Clay
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

Four Columns Instead of Four Paragraphs

Take the prose you would normally write about a step in a process — what it is for, what to be careful about, what good looks like — and force it into four columns: the stage's name, its allowed inputs, its forbidden inputs, and what it closes with. Most of the prose will not fit, and what does not fit is worth examining, because it is either craft advice that belongs in a template or a wish that was never enforceable.

The columns are chosen so that a harness can hold them. Allowed and forbidden inputs are a set membership question. "Closes with" is a postcondition — a file that must exist, a record that must have been written, a state that must have changed. None of the four asks anyone to be careful.

The Interesting Column Is the Third One

Most process documents have an implicit allowed column and no forbidden column at all, and that omission is where the failures live. Saying a stage may see the design brief and the target's current state is useful. Saying it may not see the source-language sibling is the sentence that makes the stage a different stage than it would otherwise be.

Writing the forbidden column also forces an honest audit. You will find stages where the forbidden item is genuinely required — a stage that writes files needs paths — and that is not a failure of the exercise, it is the exercise working. Those are the stages that have to be protected some other way, and knowing which ones they are is the entire input to the rest of this track.

Contracts Compose Into Pipelines, and Pipelines Are Data

Once each stage is four columns, a pipeline is an ordered list of stages plus a few flags: which stages restrict which inputs, which paths this pipeline may land, which record kind it stamps, what its gates are. That is a registry entry. Adding a ninth pipeline becomes a data change rather than a new subclass, and — more importantly — every guard the harness already knows how to apply is available to the new pipeline for free.

The difference shows up not when you add the ninth pipeline but when you change one rule that applies to all eight. With the contract scattered through code that is eight edits, and nobody can tell whether one was missed. As data it is one edit and the readers follow. The value of keeping pipelines as data is not that adding is cheap — it is that consistency is the default.

If a stage's rules cannot be written as allowed inputs, forbidden inputs, and a postcondition, they are craft rather than contract. Craft belongs in the template that the human reads; contract belongs in the registry the harness reads. Mixing them is how a load-bearing rule ends up as a sentence in a document nobody can enforce.

Code

One pipeline's contract, in full·text
STAGE      ALLOWED INPUTS            FORBIDDEN            CLOSES WITH
---------  ------------------------  -------------------  ----------------
take       brief, claim state        -                    active claim

sweep      anchor sample, neighbor   teaching from        survey notes,
           floor, live docs, the     memory               logged
           subject's real usage

plan-gate  survey notes              -                    approval of the
                                                          named fields

compose    approved plan, schema     batched writes,      full tree + full
           references                private-repo links,  metadata + the
                                     hand-stamped record  mandatory note

register   the live catalog files    authoring a NEIGH-   catalog wiring +
                                     BOR's half-landed    coherence check
                                     entry

ko-cold    every target-language     EVERY source-        repairs, and a
           fragment                  language fragment    near-empty flag
                                                          list

review     the finished tree read    the author's prose   a verdict and a
(default   cold, a fixed request     standing in for      rejection log,
 ON)       form                      the artifact         from a fresh
                                                          instance

verify     tree + log                -                    all gates green

land       verified tree             -                    one commit, one
                                                          stamp, one entry

# Every cell is decidable. Not one of them says "be careful".

External links

Exercise

Take one multi-step process you run regularly and write its contract table: stage, allowed inputs, forbidden inputs, closes with. Fill the forbidden column last and do it honestly — most stages will start empty. For every empty forbidden cell, ask whether that stage has ever gone wrong by using something it should not have, and if it has, you have just found the missing row.
Hint
The forbidden column is easiest to fill from incident memory rather than from principle. Think of the last three times the output was wrong in a way nobody caught immediately, and ask what the person or process was looking at when they produced it.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.