The Rebuild

Thirty-one commits from the starter project to the finished submission. Each one is a single idea, each one builds and passes, and each decision is recorded in an ADR at the moment it was taken.

How each commit is written up

Not a diff to interpret — a numbered list to work through:

Why — the defect or the pressure that makes this commit necessary.
The edits — every file to create, given in full; every file to change, given as find this exact text / replace it with this. The “find” block is the code as it stands after the previous commit.
Re-approve — where behaviour changed, with the diff command to read before you accept it.
Verify — mvn clean test, and the exact test count you should see.
Commit — the full message as a copy-pasteable heredoc.

Every step here was executed and verified

This is not a plan. The sequence was built end to end against the real starter project, and all 31 commits were checked out one at a time and built clean — mvn clean test, 31 for 31, no failures. The test counts in the tables below are the real ones.

Every step on these pages is generated from that repository, so the instructions and the code cannot drift apart.

The shape of it

Five phases. The order is the whole argument: you cannot safely change code whose behaviour you have not written down, so the first eleven commits add no production code at all.

1–5 · Baseline and build hygiene
Nothing here changes a line of behaviour. It makes the project honest about what it is, and reproducible for whoever opens it next.
6–11 · The safety net
Six commits, no production code touched. By the end, every defect in the supplied program is written down in a file that fails if it silently changes — including four crashes and one case of silent data loss.
12–19 · Exceptions and the domain API
The headline requirement of the Intermediate tier. Three supplied exception classes that nothing referenced get wired in one case at a time, and the two signatures that stop making sense once they are get changed deliberately.
20–25 · Persistence and structure
Three defects in the file format, each fixed where it lives before anything is moved. Then the two structural moves that the golden master proves changed nothing.
26–31 · The console, and the write-up
The ninety-line static method gets a seam, the menu stops being two lists kept in step by hand, the last crash goes, and the README gets written last — so it describes what the code does rather than what was planned.

The rules this history follows

Rules

One idea per commit. If the message needs the word "and" to describe what changed, it is two commits.
Every commit builds and passes. An assessor may check out any of them. Verified: 31 for 31.
A refactor changes no behaviour, and proves it by leaving the approved transcript untouched. Six commits here say exactly that.
A fix changes behaviour, and shows it by re-approving the transcript, with the message quoting what the user now sees instead.
Subject: imperative, under 50 characters, no full stop. Body wrapped at 72, explaining what was wrong, never restating the diff.
Decisions go in docs/adr/ in the same commit as the change they justify.

Phase 1 · Baseline and build hygiene
1	chore	add the starter project exactly as supplied
2	build	replace the placeholder groupId
3	build	compile with --release 11
4	build	add a Maven wrapper pinned to 3.9.16
5	chore	ignore the state file the application writes
Phase 2 · The safety net
6	test	pin the add-and-list journey with a golden master
7	test	extend the golden master to every menu option
8	test	extend the golden master across a restart
9	test	extend the golden master to unparseable menu input
10	test	characterise Book
11	test	characterise the library as a collection of books
Phase 3 · Exceptions and the domain API
12	fix	report a failed borrow or return instead of crashing
13	refactor	give the domain exceptions a common supertype
14	fix	signal a missing book with BookNotFoundException
15	fix	distinguish an already-borrowed book from a missing one
16	fix	distinguish a book that was never borrowed from a missing one
17	refactor	drop the boolean returns no caller can act on
18	refactor	return Optional from searchBook
19	refactor	derive borrow and return from a shared requireBook
Phase 4 · Persistence and structure
20	fix	stop a separator in a title from corrupting the saved file
21	fix	report a truncated state file instead of crashing on an index
22	fix	keep the library intact when the state file will not parse
23	fix	raise LibraryStorageException from save and load
24	refactor	extract LibraryRepository from Library
25	refactor	move the domain types into a domain package
Phase 5 · The console, and the write-up
26	refactor	extract LibraryConsole from Main
27	test	drive the console through its injected streams
28	refactor	replace the menu constants with a MenuOption enum
29	fix	keep serving the user when the menu choice is not a number
30	docs	correct a stale cross-reference in ADR 0006
31	docs	document the approach, decisions and deviations

The rules this history follows

Setup

All thirty-one

The decisions