Vibeleaderboard
← Course overviewModule 07 · Build software you can explain · Beta
Lesson 7.5

Module contents

Build software you can explain

Lesson 5 of 5

Release only what you can explain and recover from

The committee will start relying on the comparison the first time it uses a printed table to choose a supplier. That moment is a release, however informal, and it should have conditions. This lesson connects four things to the same small program: input the program should not trust, secrets it must never contain, dependencies it must not acquire quietly, and the evidence and way back that a release needs. It ends with a transfer checkpoint on a change to the program and a way to review your own answer. The scenarios remain authored for the course.

Numbered links identify sources. Underlined terms offer a definition without leaving the lesson.

Input the program should not trust

The quote comparison treats its input according to its contract: the header is checked, every required value is checked for presence, every amount goes through money, the installation column must say yes or no, and a record that fails is reported rather than guessed at. These are the input checks this version implements, with remaining limits: a multi-line name is not covered, negative delivery or guarantee values are not rejected, and a file with the right header but the wrong meaning in a column could pass. It stops being enough the moment input arrives from people the program does not know.

Suppose the committee later asks for a web page where any member can type a supplier name and see that supplier's quote. The page's code now takes text from a browser and uses it to look something up, and if it builds a database query by pasting the typed text into the query string, a member can type a fragment that changes the query's meaning. MDN's introduction to website security shows exactly this shape, a query assembled around a user-supplied name, and gives the remedy: pass the value separately as a parameter so the database treats it as data rather than as part of the command, and never trust data that arrives from the browser (MDN, Website security, checked 2026-09-29). That is an flaw, and the point for a non-programmer is its location. It is not in the arithmetic; it is at the boundary where untrusted input meets a command. When reading a change that adds such a boundary, ask what happens if the input is not what the author imagined, exactly as lesson 1 asked for the blank installation price.

Secrets and dependencies

The program has no : no password, key or token that would let someone act as the committee. That is a consequence of its non-goals; it fetches nothing and sends nothing. If a later change had it download quotes from a supplier portal that requires a login token, the token would be a secret, and two rules follow from module 2's account of credentials. It must not be written into the program's text or into the quotes file, because both are shared and copied, and it should be as narrow and as short-lived as the service allows. GitHub's documentation for its own access tokens states the practice for that service: treat tokens like passwords, choose the minimal permissions and repository access necessary, and add an expiration date (GitHub Docs, checked 2026-09-29). Not every service offers expiring or narrowly scoped credentials; where it does, use them, and where it does not, the same three questions still apply to any secret an agent proposes to use: where does it live, what can it do, and when does it stop working.

An agent adding a feature will sometimes add a secret and a third-party dependency in the same change, because the quickest route to a supplier portal is a package that handles the login. Lesson 3 gave the questions for the dependency. The release question is simpler: was each one added on purpose, with the organizer's agreement, and is it written down? A change that arrives with a new package and a new token in it, unannounced, is not ready to release whatever its checks say.

Conditions for a release

A is something that must be true before people rely on a version of the program. For the comparison, four are enough, and each comes from an earlier lesson. The checks derived from the specification pass, and the ones that matter for the change have been seen to fail first. The known limits are written down: the input contract's edges, the multi-line name, and anything else observed but undecided. Every dependency beyond the standard library and every secret is listed, which for this version means none. And there is a way back.

The way back is the : what to do if the released version turns out to be wrong. For this program it is short because the program keeps no state. The previous version is kept under version control, the installed-price fix was a single line, and a wrong table can be regenerated by rerunning the corrected program on the same quotes file with the same requested length. If the committee had already acted on a wrong table, recovery also means telling them, promptly if a decision is time-sensitive, with the corrected table beside the old one; the program cannot undo a decision, and the record of which version produced which table is what makes the conversation possible. A program that stored bookings or sent emails would need more: a copy of the stored data from before the change, and an account of which external effects happened, which module 3 called the difference between rewinding a conversation and undoing an action.

The practitioner guide cited in lesson 1 ends on a caution that belongs here: however carefully you list your unknowns, unknown unknowns remain (field guide, July 2026). A release is a decision made on evidence and a recovery path, not on the absence of visible problems.

Transfer checkpoint: a change to the comparison

The committee asks for one change. Some suppliers now quote per metre rather than for the whole fence, so the quotes file gets an eighth column, pricing, with the value total or per_metre. For a per_metre row the installed price is the quoted price multiplied by the requested length, plus the installation price if installation is not included; the installation price is never multiplied. Existing rows carry total and must produce exactly the totals they produce today. The specification's new behavior example, authored for the checkpoint:

supplier       length_m  price  installation_included  installation_price  delivery_weeks  guarantee_years  pricing
Weald Fences   40        55     no                     300                 5               10               per_metre

Expected for length 40: Weald Fences  installed 2500  (55 x 40 = 2200, plus 300)

An agent delivers the change. It edited read_quotes to require the eighth column, added pricing with the value total to every row of both fixture files, and reports "all nine checks pass", with the run output attached. Reading the diff, you find that for a per_metre row the delivered code multiplies both the price and the installation price by the length.

Work through the following without running anything.

  1. Explain the data path for the new column: where the value enters, which function must read it, where the multiplication belongs, and what the program should do with a row whose pricing value is blank or misspelt.
  2. Say whether any of the nine existing checks would catch the delivered flaw, and why. Describe the check you would add, with its expected value taken from the example above, and what its output would be on the delivered code.
  3. You have the agent's run output and its edited check file. State what the passing run establishes, what it leaves unobserved, and what you would look for in the edited check file before believing the run.
  4. Write the record for this change as the committee should receive it: the behavior specification for the new column, the data path annotated with where the new logic sits, the checks that were seen to fail and then pass, the known limits, and the release and recovery conditions.

To review your own answer, apply the module's questions to it in order. For question 1, the value enters as a field of each record in read_quotes, is read where the installed price is computed, and the multiplication belongs beside the yes-or-no decision in installed_price, applied to the price only; a blank or misspelt pricing belongs with the other refused values, reported by row, not treated as total. For question 2, every existing row now carries total, so no existing check exercises the per_metre branch and all nine genuinely pass; the check to add gives the program the Weald row and expects 2500, and on the delivered code it would report a total of 14200, because 300 is also multiplied by 40. For question 3, the run establishes that the total behaviors still hold on the edited fixtures and nothing about per_metre; in the edited check file, confirm that the fixtures gained the column as reported, that no expected value was changed, and that no check was removed. For question 4, a record that omits the added check's failing run on the delivered code, the known limits or the way back is not yet a reviewed change, however complete its description of the code.

Carry this forward

  • Input handling is a question at every boundary where untrusted data meets a command; injection lives at that boundary, not in the arithmetic, and the remedy is to pass data as data.
  • A secret must live outside the program's text and shared files, do as little as the task needs and expire where the service allows; a dependency or secret added unannounced makes a change unready to release.
  • Release conditions: checks pass and were seen to fail first, known limits are written down, dependencies and secrets are listed, and there is a way back.
  • A recovery path for a state-free program is rerunning a kept previous version on the same input; telling anyone who acted on wrong output, stored data and external effects each need their own plan.
  • A reviewed change carries the specification, the annotated data path, the checks with their failing and passing runs, the known limits and the release and recovery conditions; a passing run alone is none of these.

Lesson check

An agent delivers the per-metre change together with a new package for reading spreadsheets and a saved login for a supplier portal "so quotes can be fetched later". All checks pass. What is the right release decision?

Choose an answer for each question.

This is a practice check. Answers reset when you leave this page. Results are not saved and do not place you in another module or award a qualification.

Whether the output is code or a report, repeated and longer work needs reliable evidence, recovery and sensible stopping rules. Module 8 takes the same habits, behavior stated first, checks that can fail, and a way back, into workflows that run many times without a person watching each run.

Module 7 quiz: put the ideas together

1. The organizer writes: "The program should never surprise the committee." Which restatement turns that intent into something a check can test?
2. A member edits the quotes file in a text editor and saves a supplier's address in the notes column as "12 Mill Lane, Oxford" without quote marks. What does the CSV reader do with that record?
3. Why can the comparison be run twice on the same quotes file and produce the same output, when module 5 warned that a repeated read may return changed rows?
4. An agent replaces the twenty lines of compare with a call to a data-analysis package that reads, filters and sorts the table in three lines, and says the behavior is identical. Which question gets at the consequence the organizer most needs to know?
5. Before fixing the flawed version, a learner runs the check file and gets a traceback ending in "FileNotFoundError: No such file or directory: 'quotes.csv'", with no PASS or FAIL lines. What has the run shown?
6. The organizer asks a second agent to review the first agent's change, and gives it the first agent's summary of what the change does. What is missing for this to count as independent review?
7. Three weeks after the committee chose a supplier using a table from the flawed version, the installation flaw is found. Nobody remembers whether the wrong Hedgerow total affected the choice. Which step tells you whether the committee needs to revisit its decision?
8. An agent's change reads a portal token from a line at the top of the program, "so it is easy to find". Which objection is correct?

Choose an answer for each question.

This is a practice check. Answers reset when you leave this page. Results are not saved and do not place you in another module or award a qualification.

Sources · Reviewed 2026-09-29
  1. 9. MDN Web Docs: Website security
  2. 10. GitHub Docs: Managing your personal access tokens
  3. 5. Thariq Shihipar (claude.com): A field guide to Claude Fable: finding your unknowns (July 2026)

Sources support nearby explanations. Product details can change. Scenarios and model results are authored illustrations unless a lesson explicitly identifies a recorded execution. Module 7 identifies its offline code checks.