Skip to content
C.W.K.
Lesson 07 of 07 · published

The Rule Lived in a Document

~14 min · promotion, hard-checks, review, evolution

Level 0Cold Workshop
0 XP0/58 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete

A Review That Read the Document Against the Code

Lesson 2 of this track argued that a lesson which stays prose will be re-learned, and that the document is where lessons go to be forgotten politely. It is easy to agree with that about other people's processes. On 2026-10-22, in the middle of a trip that had produced a new travel film most days, the workshop's fifth review (Coop 601) tested it on the workshop itself. The method was plain: read the travel pipeline's procedure rule by rule and, for each one, find the code that holds it.

Six of the rules born on the trip had no code at all. The known-misreads table, the rule that the owner's camera shots replace phone pictures of the same moment, the PIN-free review link, the retry for a cover refused for quota, the named translation reviewer, and the folder layout for a corrected upload all lived in the document and nowhere else. The procedure's own history now says it without softening: the rules "had reached the pipeline unevenly". Unevenly is the precise word. Each rule had been followed, some of the time, by a session that had read it. The hourly cover retry had been written twice, as two episodes' own scripts. Two corrected uploads had built their revision folders by hand. The Nerja dubs had kept logs and a hand-made file of applied fixes instead of a record of the translation review. One camera swap lived as a row typed into a media list, where the next re-fetch could have dropped it.

The owner's answer was one line: "이 세션에서 모두 고쳐" ("fix all of it in this session"). Not a backlog, not a ticket per finding. Every one of them, before the session ended (63bc75e).

Six Rules, Six Homes in Code

The misreads table became beacon/misreads.py: cut writes its verdict on the script sheet, beacon mobile approve and revoice refuse a listed spelling, and a readback after the voice puts every risky spot on the watch sheet (lesson 9 of track 6). The camera rule became a check that every folder of the owner's camera exports the cut touches carries a camera_checked note, with his shots entering as supplied assets bound by hash, so a re-fetch keeps them. The review link became a pipeline verb, review-link, that mints the link where Pippa's upload store lives and keeps it in out/review-links.json. The cover retry became cover, with one lock per language and every attempt on record. The translation reviewer became a gate: dub-voice refuses to pay for a language whose cold review is not on record as Grok's, or Kimi's with Grok's failure written down, with every finding decided and bound to the current sheet (beacon/review_decisions.py). And the revision layout became revise, which moves the superseded upload's receipts and movie into revisions/rNN/ beside a superseded.json; the corrected cut then renders and goes up as its own private video, and that upload is stamped as the successor (beacon/revisions.py).

None of these is clever. Each is the rule the document already stated, moved to the one place a session cannot skip: the command that would otherwise do the wrong thing.

The Record Was Typed Too

The same review found the gap one level up, in the record of the work. On one travel production, the audio, assemble, validate and upload rows had been typed by hand, all within a single second, after the upload had already happened. Each row was true in the sense that the stage had run. None was evidence of what the stage had measured, and verification had accepted them because it only asked whether a row existed.

Now the talk, travel and translation renderers post their own stage rows, each with a receipt of what the run measured. Verification binds them to the files: a validate row without a receipt naming the render that is on disk now fails, and a travel script-gate row that is not the approval on disk fails too. The failure message names the remedy, and the remedy is to run the finishing stage again, never to type the row more carefully. And because two runs writing one production would race each other's records, a writing stage takes a lock, and a second run stops and says who holds it. Lesson 1 of this track said that a stage record states only what a person actually did. The same rule now holds for the machine's half: a stage row states only what a run actually measured.

The Rule About Rules

The most instructive line in the fix is the smallest. When the misreads table was written on 2026-10-21, the procedure told the producer to add each new misread the owner catches "to this table in the same change that fixes the episode". The rule about recording lessons was itself prose pointing at prose. Review 5 changed its destination: each new misread now lands in beacon/misreads.py, and the table, in the same change that fixes the episode. Within a week it was used three times, and each time the code, the document and a test arrived in one commit: an English sentence fused to a Korean particle, a heavy "sassy" that sounds like "sexy", and the hanja guard (b8a5d9a, a215157, 760c26a). That is what promotion looks like when it is a habit rather than a project: the lesson and its check are one change, so there is no window in which the lesson exists only as prose.

The Counter-Case, Today

The honest end of this lesson is a rule that is still on the wrong side of the line. From Beacon 127, the owner asked that the Chief see a travel script before he does: "대본이 나오면 아빠가 보기 전에 치프 피파가 먼저 보고 아빠한테 보고해" ("when a script comes out, Chief Pippa looks at it first, before I do, and reports to me"). Beacons 127 and 129 carried it as an instruction in their work orders, while step 4 of the procedure still told the producer to hand the script straight to him. On 2026-10-27 baseline 1.12 wrote it into the procedure (b401392): the producer parks the work with the path and sha256 of SCRIPT.md and stops before synthesis; the Chief reviews that exact file and reports; a new sha256 is a new review; the approval receipt quotes the owner, never the Chief.

That moved the rule from two work orders into the doctrine. It did not move it into code. No Beacon command checks that a Chief review exists for the sha256 being approved. beacon mobile approve checks the owner's words and refuses a source reference that already approved a different script, and that is all. Today the gate holds because sessions read step 4. By this lesson's own argument, that is the weaker kind of holding, and it should be said in exactly those words rather than discovered later as an uneven reach.

Audit your doctrine against your code, rule by rule. A procedure document describes what should happen; only the commands describe what will. For every rule, name the line of code that would stop a session that ignored it. Where there is none, either write it, or write down plainly that the rule is held by reading alone.

Code

A stage row is evidence only with its receipt (verbatim, beacon/cli.py, as of 2026-10-27)·python
def _validate_receipt_gate(logs: list[dict], facts: dict) -> bool:
    """A `validate` row the run itself posted, naming the render that is on
    disk now. A row typed with `beacon stage validate` carries no receipt and
    never passes: the renderer's finish (talk, mobile, dub-finish for
    translations) or video stage posts it when given --delegation."""
    want = _validate_receipt(facts)
    rows = [r for r in logs if r["event"] == "stage_done" and r.get("stage") == "validate"]
    held = [(r.get("payload") or {}).get("receipt") for r in rows]
    if any(isinstance(h, dict) and all(h.get(k) == v for k, v in want.items()) for h in held):
        return True
    if not any(isinstance(h, dict) for h in held):
        print("-- validate was logged without the run's receipt (typed by hand?): run the renderer's"
              " finish / dub-finish (or video) with --delegation so the run records what it measured")
    else:
        print("-- the validate receipt names another render or other inputs than the files on disk now:"
              " run finish / dub-finish again")
    return False
Sketch: where each rule lived, and where it lives now (as of 2026-10-27)·text
rule                       before 2026-10-22            now
-------------------------  ---------------------------  ------------------------------------
known misreads             a table in the doc           beacon/misreads.py: cut flags;
                                                        approve, revoice refuse;
                                                        readback -> WATCH.md
his camera beats the phone the doc; one hand-typed row  camera_checked per folder; supplied
                                                        assets bound by hash
PIN-free review link       the doc                      pipeline.py review-link,
                                                        out/review-links.json
cover retry after quota    two episodes' own scripts    pipeline.py cover (lock, history)
translation reviewer       the doc; hand-made fix file  review_decisions.py; dub-voice refuses
corrected-upload layout    two hand-built folders       revisions.py: revise, superseded.json
stage rows                 typed by hand                renderer posts receipts; verify binds

Chief reads the script     two work orders              the doc (baseline 1.12)
                                                        code: none yet

Exercise

Take the procedure document your team trusts most (a runbook, a release checklist, a contribution guide). For each rule in it, write down the line of code, test, or hook that would stop someone who ignored it. Mark every rule where the answer is "nothing". Then pick the one that has already been worked around twice, and promote it, in the same change as the next fix that needs it.
Hint
Look for evidence of hand implementation: scripts in personal folders, one-off fixes in a single project, records written after the fact. Those show which prose rules people are already paying for by hand. Rules nobody has ever had to implement locally may be fine as prose for now; say so in the document.

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 in — Please sign in to comment.

No comments yet — be the first.