Lessons

Lessons

This page mirrors docs/lessons/register.md in the repository, which is canonical. When the two disagree, the register is right.

A lesson teaches one merged change as a page with widgets the reader can operate, kept as it was on the day the change landed. It records what the change taught, where the live atlas records what the system is now.

The lessons run at https://0xfauzi.github.io/kstrl/lessons/, not here: a wiki page is rendered through a sanitiser that strips scripts and styles, and a lesson is a page you operate. This page carries the index and the record.

The rule. A shipped lesson is immutable. The one edit it may receive is a supersession banner: when a later change reverses what a lesson taught, the new lesson's register entry names what it reverses, the old entry gains superseded-by:, and the old lesson gains a banner at the top saying so. The register's checker fails a reversal that is not recorded in both places.

PR 221: kstrl as a control loop, and the end state it defines

• Lesson: https://0xfauzi.github.io/kstrl/lessons/pr-221.html
• Pull request: https://github.com/0xfauzi/kstrl/pull/221
• Range: 94fdbbd..79196de
• Reproduce its sweeps: docs/lessons/verify/pr-221/ in the repository

What the lesson taught. The end architecture as one clickable map: the atlas's own drawing of kstrl with the components the R10 plan reaches marked, a TODAY and END STATE toggle, a per-component panel, and a thirteen-step walk of one spec from labelled issue to journal that lights, on the same drawing, which component acts and which component measures each step. The walk makes the two open loops visible by their missing amber card: the engineer's inner loop (only the breaker and the path guard measure it, and neither reads the code) and the unbuilt operate loop. Eight decisions, each as a rule the reader operates: who may say a story is done (the set-point agreement rule with its blocking rule folded in), why the agent sees only what is failing now (the rank rule, with the corrected legacy special case), what happens when the review budget runs out, why the daemon can refuse work (the admission gates in the order the code evaluates them, with R10.7's bound placed where issue #228 puts it), how autonomy is earned and lost (the ladder with its clamps and the manual-override note), the order the context is assembled and why the memory file follows the retry context, why a sensor must run by hand first, and which loop a change belongs to (the observe band is not a loop; a sink is never control flow). Every rule was swept outside the page in Python, and the page's inline script was then run under node against the same grids: 960, 1560, 144, 110592, 75, 80, 31 and 34 rows agree, and every "try this" move reproduces. The build order, the graduation rule, the three prohibitions and where each new file lives are one table.

Two corrections the sweeps forced on the lesson's own drafts: the level-triggered retry context is bounded, not smaller (it is longer than today's for one or two attempts and adds one history line per further attempt where the old format adds a full failure text), and "every permission in the bundle is monotone" only holds once the merge gate is read as a restriction rather than a permission. One place the material and the brief disagree, decided for the material: issue #228 inserts the open-PR bound into the gates tuple after check_budget, which is before the inbox cap and the factory lock, so the lesson draws it there and says the issue's "only when everything else admits" holds for the three ledger gates only.

What the lesson could not confirm, because the run data is not in the repository: the journal figures (five runs, eighteen entries, review:prd_criterion at five, the reviewer at fourteen of seventeen signatures, avg_iterations at 1.00), the design's claim that the one-open-PR default is proven in production elsewhere, and the "after PR #237" state of the command tree, which is that pull request's description of itself while it was open. The tracker section every R10 issue points at was still absent from main when this was written; PR #239 restores it.

Terms it introduced, defined in the register's glossary: set point, sensor, error signal, controller, actuator, disturbance, windup, level-triggered, advisory first, flow control, dampener, safe mode, golden patterns, memory file, human on the loop, loop nest, set-point agreement, ks sense, rank rule, admission gate, flag bundle.