From 321889005d8966f72aac3a52f443010009ef2aa3 Mon Sep 17 00:00:00 2001 From: Ocean Bennett <204957658+undergroundrap@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:01:14 -0400 Subject: [PATCH 1/2] docs: draft 0027 program-driven language development (proposed) --- ...opt-program-driven-language-development.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/decisions/0027-adopt-program-driven-language-development.md diff --git a/docs/decisions/0027-adopt-program-driven-language-development.md b/docs/decisions/0027-adopt-program-driven-language-development.md new file mode 100644 index 0000000..eedfda9 --- /dev/null +++ b/docs/decisions/0027-adopt-program-driven-language-development.md @@ -0,0 +1,48 @@ +# 0027: Adopt Program-Driven Language Development + +Date: 2026-09-23 +Status: proposed 2026-09-23. BDFL rules and merges. + +## Context + +Hum's north star (0024) is a claim about humans and agents reading, writing, +and verifying real programs. Prose cannot carry that claim; programs must. +This record adopts the loop Hum now follows: real programs drive the +language, friction is recorded per program, and additions clear a +general-fix test before they land. + +## The loop + +1. **Real programs drive the language.** wordfreq is the first real program + (WO27). Next: the config-file parser and the state machine with ownership + transfer chosen by 0026 to stress the closed-world accountability + objective — not to demo syntax. +2. **Friction goes into per-program friction ledgers.** Every friction point + is classified: program gap, tooling gap, docs gap, or language gap. The + ledger is a deliverable alongside the program. +3. **Missing surface is a STOP; gaps become decision records before + implementation.** Worked examples: 0021 recorded the missing newline-literal + mechanism as an open dependency blocking wordfreq's Part 2 instead of + inventing one; 0022 resolved it as a decision record first. +4. **The general-vs-specific test.** An addition must be the general fix, not + a one-program special case. Program-specific helpers are rejected by + default. Precedent: 0021's "no general string library" ban — `text_split` + is the single tokenization primitive; anything further needs its own + decision record. +5. **Finished programs join the bake-off corpus.** The scorecard is re-run + against each finished program, so the 0014 ownership bet keeps being + tested (backlog item 2). Corpus provenance is recorded per program. +6. **"Best for humans and agents" is measured four ways:** the friction + ledgers; the agent repair benchmark (agents fixing broken programs — + success rate and attempts); the human review study (backlog item 3); and + CI minutes per PR. + +## Consequences + +- No language addition lands without the ledger entry that motivated it and + the decision record that specified it. +- The general-vs-specific test is a review gate: a proposal that serves only + its motivating program is rejected by default. +- The bake-off scorecard and the four measures are re-run as programs finish. + A program that stops the loop's measures from moving is reported, not + hidden. From 290972f23ab1fed880b5d510114eedef5c3b4d3c Mon Sep 17 00:00:00 2001 From: Ocean Bennett <204957658+undergroundrap@users.noreply.github.com> Date: Wed, 23 Sep 2026 00:05:04 -0400 Subject: [PATCH 2/2] docs: accept 0027 per pre-issuance review (BDFL 2026-09-23) --- ...opt-program-driven-language-development.md | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/decisions/0027-adopt-program-driven-language-development.md b/docs/decisions/0027-adopt-program-driven-language-development.md index eedfda9..7df916d 100644 --- a/docs/decisions/0027-adopt-program-driven-language-development.md +++ b/docs/decisions/0027-adopt-program-driven-language-development.md @@ -1,7 +1,7 @@ # 0027: Adopt Program-Driven Language Development Date: 2026-09-23 -Status: proposed 2026-09-23. BDFL rules and merges. +Status: accepted 2026-09-23 (BDFL ruling on review at 6b36621). ## Context @@ -16,7 +16,9 @@ general-fix test before they land. 1. **Real programs drive the language.** wordfreq is the first real program (WO27). Next: the config-file parser and the state machine with ownership transfer chosen by 0026 to stress the closed-world accountability - objective — not to demo syntax. + objective — not to demo syntax. Programs 2 and 3 are the current order; + wordfreq's ledger may reorder them — update this record rather than + treating the order as fixed. 2. **Friction goes into per-program friction ledgers.** Every friction point is classified: program gap, tooling gap, docs gap, or language gap. The ledger is a deliverable alongside the program. @@ -33,16 +35,18 @@ general-fix test before they land. against each finished program, so the 0014 ownership bet keeps being tested (backlog item 2). Corpus provenance is recorded per program. 6. **"Best for humans and agents" is measured four ways:** the friction - ledgers; the agent repair benchmark (agents fixing broken programs — - success rate and attempts); the human review study (backlog item 3); and - CI minutes per PR. + ledgers (exist today); the agent repair benchmark — agents fixing broken + programs, success rate and attempts (to be built); the human review study + (backlog item 3; to be built); and CI minutes per PR (exist today). ## Consequences -- No language addition lands without the ledger entry that motivated it and - the decision record that specified it. +- Every language addition cites its motivating evidence — a friction-ledger + entry, a benchmark or measurement result, or a study — and the decision + record that specified it. Some legitimate additions (safety profiles, + perf-debt fixes, 0026 study results) will not come from program friction. - The general-vs-specific test is a review gate: a proposal that serves only its motivating program is rejected by default. - The bake-off scorecard and the four measures are re-run as programs finish. - A program that stops the loop's measures from moving is reported, not - hidden. + A finished program that moves none of the measures is reported: a program + that teaches nothing is itself a signal.