A Log Needs Teeth or It Rots

Every Optional Field Ends Up Empty

A log that only the process document requires is another prose rule, and it decays exactly the way the first track described: not because anyone objects to it, but because skipping it costs nothing at the moment of the decision and shows up nowhere afterward.

The version of this everyone has seen is a metadata field that was supposed to be maintained by hand and is now years stale on most records. Nobody decided to stop updating it. It simply never blocked anything, so it drifted out of the set of things people do.

Teeth Means Something Downstream Depends On It

The fix is not enforcement in the social sense. It is making the log load-bearing, so that its absence is felt immediately by the person who skipped it.

A gate reads the log and fails on gaps. Verification checks that every required stage has an entry against this unit of work. An incomplete log is a failed verification, and a failed verification blocks the landing.

The landing requires a recorded pass. Not "you should verify before landing" — the landing command looks for a passing verification event and refuses without one. There is an override, and the override is itself recorded, which is the right shape: possible, and never accidental.

A guard derives its state from it. The seal from the third track works out where the run is by reading which stages have been logged, which means skipping an entry has an immediate, visible consequence.

Notice what the three have in common. Not one of them asks a person to write the record. They arrange things so that the record has to exist before the next thing can happen — the same move from discipline to structure, applied to the log itself. In the first track's ladder, this is what lifts a log from rung 1 to rung 4 — a record that lives only in the process document is advice.

The New Mistake This Creates, Named on Purpose

Making a log load-bearing means forgetting to write an entry now breaks something. That is the design working, and it is also a genuinely new way to be wrong that did not exist before. The direction is chosen deliberately: the failure blocks work you were entitled to do, rather than allowing work you were not, and the error message names the repair.

It is worth writing that down in the contract rather than letting the next person discover it under pressure. A system whose new failure modes are documented is one you can hand to somebody else.

If nothing breaks when a record is missing, the record is decoration and will be gone within a year. Find one downstream consumer that genuinely needs it, and wire the dependency — one real consumer does more for data quality than any amount of documentation about how important the field is.

Code

The gate that gives the log its teeth·python

def gate_stages_logged(delegation_id: int, pipeline: dict) -> tuple:
    """Every required stage has an entry against THIS unit of work.

    Note the filter: entries are matched on the delegation, not on
    the target. A stage logged against the target alone is invisible
    here - which produced a confusing failure where the CLI printed
    success and the gate reported the stage missing. The fix was to
    bind the entry to the session's own claim at write time.
    """
    logged = {e["stage"] for e in fetch_log(delegation_id=delegation_id)
              if e["event"] == "stage_done"}
    missing = [s for s in pipeline["required_stages"] if s not in logged]
    return (not missing, {"missing": missing})


def land(delegation_id: int, force: bool = False):
    """No green verification, no landing."""
    passed = [e for e in fetch_log(delegation_id=delegation_id)
              if e["event"] == "verified" and e["passed"]]
    if not passed and not force:
        raise SystemExit(
            "no passing verification logged on this unit of work - "
            "run it first (--force to override, which is on the record)")
    ...


# The override exists and is itself an event. "Possible but never
# accidental" is the shape to aim for: a guard with no override
# gets removed the first time it is wrong at 2am.

Exercise

Find a metadata field in your systems that is supposed to be maintained by hand and check how stale it is. Then decide its fate honestly: either wire one real downstream consumer that fails when it is missing, or delete the field. A field that nothing depends on and everyone is asked to fill in is worse than either option, because it costs attention and returns nothing.

Hint

The best consumer to wire is one that the person filling in the field also runs. A dependency felt by a different team is enforcement; a dependency felt by the same person minutes later is feedback, and feedback changes behavior where enforcement produces resentment and workarounds.

Every Optional Field Ends Up Empty

Teeth Means Something Downstream Depends On It

The New Mistake This Creates, Named on Purpose

Code

External links

Exercise

Progress

Comments 0