AGENTS.md

@@ -11,7 +11,7 @@
 - Gitea queues Actions runs that `/repos/{owner}/{repo}/actions/tasks` does not
   list, so an empty task list says nothing about whether CI ran; read
   `/repos/{owner}/{repo}/commits/<sha>/status`.
-- README goal 14 is gated at 7.0 on the `comprehension-panel` skill, and below it
+- README goal 2 is gated at 7.0 on the `comprehension-panel` skill, and below it
   nothing else merges — no feature, no category, no data — bar a security fix and a
   dependency bump. `todo.md` carries the round: the nine-seat findings run at depth 1,
   a PR per item it names, then the run again, until the score passes. At or above 7.0

DATA-LICENSES.md

@@ -14,7 +14,7 @@ Every shipped dataset, its source, its licence and the attribution it asks for.
 | `sv_SE/first-name.tsv`, `last-name.tsv` | [SCB](https://www.scb.se/) names with at least two bearers, 31 December 2022 | CC0 1.0 | "Källa: SCB" | `data-import/names-se.py` |
 | `en_US/first-name.tsv` | [SSA](https://www.ssa.gov/oact/babynames/) baby names, births 1930 to 2020, through [hackerb9/ssa-baby-names](https://github.com/hackerb9/ssa-baby-names) | public domain | none required | `data-import/names-us.py` |
 | `en_US/last-name.tsv` | Census Bureau surnames occurring 100 or more times, 2010 | public domain | none required | `data-import/names-us.py` |
-| `sv_SE/sex.tsv`, `sv_SE/birth-number.tsv`, `sv_SE/title.tsv`, `en_US/sex.tsv`, `en_US/title.tsv`, `misc/car.tsv` | curated; Skatteverket's test birth numbers are facts, and `car.tsv` waits for an international source (goal 11) | — | — | — |
+| `sv_SE/sex.tsv`, `sv_SE/birth-number.tsv`, `sv_SE/title.tsv`, `en_US/sex.tsv`, `en_US/title.tsv`, `misc/car.tsv` | curated; Skatteverket's test birth numbers are facts, and `car.tsv` waits for an international source (goal 12) | — | — | — |
 | `misc/currency.tsv` | [datasets/currency-codes](https://github.com/datasets/currency-codes); symbols from [Unicode CLDR](https://github.com/unicode-org/cldr) `en.xml` and `root.xml` | PDDL 1.0; [Unicode License v3](https://www.unicode.org/license.txt) | CLDR: "Copyright © 1991-2025 Unicode, Inc. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other countries." | `data-import/currency.py` |
 | `misc/httpmethod.tsv` | [IANA HTTP Method Registry](https://www.iana.org/assignments/http-methods/) | [public domain](https://www.iana.org/help/licensing-terms) | none required | `data-import/httpmethod.py` |
 | `misc/httpstatus.tsv` | [IANA HTTP Status Code Registry](https://www.iana.org/assignments/http-status-codes/) | [public domain](https://www.iana.org/help/licensing-terms) | none required | `data-import/httpstatus.py` |

README.md

@@ -806,51 +806,52 @@ the Development section below, and who ships a register the four above then draw
    worth switching to, and every goal below it is what that costs. Merit is only
    half the goal: once the grammar, the data and the CLI are complete and stable,
    it ships where those developers install from and is announced where they read.
-2. **Valid by construction** — every value passes the check its real consumer
+2. **Understanding the code is part of the product** — it is a compiler with static
+   fences behind a small API, it will grow, and the people who extend it will not be
+   the people who wrote it. So reading cost is judged alongside behaviour: reaching
+   the unit behind a symptom without asking a person, changing one piece without
+   holding the rest, names that tell the truth, and a file that stands with no second
+   document open beside it. A simulated reader panel scores those four, the score is a
+   ratchet no release lowers, and [`AGENTS.md`](AGENTS.md) says what each pull request
+   owes it.
+3. **Valid by construction** — every value passes the check its real consumer
    applies; facts that belong together come from one draw, within a value and
    across categories.
-3. **Text means what it says** — a format renders as written; only `{…}` varies,
+4. **Text means what it says** — a format renders as written; only `{…}` varies,
    random characters included (`{digits(3)}`). One spelling per result; the wrong
    one is a load error naming the right one.
-4. **Every mistake is a load error** — `New` rejects the data and `NewTemplate`
+5. **Every mistake is a load error** — `New` rejects the data and `NewTemplate`
    the inline template; on a loaded generator `Fake` fails only for an unknown
    path, `FakeStruct` only for a non-struct argument or a type its tags do not
    describe, with the same error every call, and `Template.Fake` cannot fail at all.
-5. **Zero to a value in one command** — `go install`, then `fejkdata sv_SE.person`:
+6. **Zero to a value in one command** — `go install`, then `fejkdata sv_SE.person`:
    no checkout, no flag. Flags are GNU-form (`--seed 42`, `-n 3`) in any position;
    the first custom template needs no escape and no option.
-6. **Data lives in JSON** — a builtin only for what data can't express.
+7. **Data lives in JSON** — a builtin only for what data can't express.
-7. **Reproducible** — seed in, same stream out; no builtin reads a clock.
+8. **Reproducible** — seed in, same stream out; no builtin reads a clock.
-8. **Zero dependencies** — standard library only.
+9. **Zero dependencies** — standard library only.
-9. **Docs index the grammar** — every syntax feature is a heading; every example
+10. **Docs index the grammar** — every syntax feature is a heading; every example
-   runs under test and shows its output; a rule is stated once.
+    runs under test and shows its output; a rule is stated once.
-10. **Fast enough to be free** — a value renders in about a microsecond and `New`
+11. **Fast enough to be free** — a value renders in about a microsecond and `New`
     parses and validates the whole set once upfront, so generating fixtures stays
     noise against a test's own runtime.
-11. **Data is sourced, or on its way there** — a shipped fact, a name, place,
+12. **Data is sourced, or on its way there** — a shipped fact, a name, place,
     code, id or classification, is read from a register or open dataset by a
     [`data-import/`](data-import) script wherever one exists to read; where none
     does yet a small hand-written set ships and [`todo.md`](todo.md) carries the
     step that replaces it. Only non-factual copy stays authored. A sourced table
     holds the rows its source holds: none is added by hand, and one is dropped
     only by a rule the script states.
-12. **Breadth follows what most systems store** — a category is added in proportion
+13. **Breadth follows what most systems store** — a category is added in proportion
     to how many real schemas hold it: names, addresses, phones, ids, money and
     timestamps before anything domain-specific, and a catalogue serving one niche
     waits behind everything serving many.
-13. **Realism is the default, inertness is selectable** — where a value could reach
+14. **Realism is the default, inertness is selectable** — where a value could reach
     something real, a domain anyone may register or an account a bank could issue,
     the realistic breadth ships *and* so does the subset that provably reaches
     nothing, each on its own path. A fixture that looks nothing like production
     tests nothing; the caller who needs a value that can touch nothing asks for it
     by name.
-14. **A cold reader lands in the right place** — the code is judged on what it costs
-    to read, not only on what it does: reaching the unit behind a symptom without
-    asking a person, changing one piece without holding the rest, a layout whose
-    names tell the truth, and a file that stands with no second document open beside
-    it. A simulated reader panel scores those four, the score is a ratchet no release
-    lowers, and [`AGENTS.md`](AGENTS.md) says how each pull request answers to it.
-
 ## Decisions
 
 - **Options and fields share one namespace.** `format`, `weight`, `repeat`,
@@ -1248,7 +1249,7 @@ the Development section below, and who ships a register the four above then draw
   fejkdata has no business making.
 - **`misc.loglevel` is a table keyed by the code, rendering POSIX's keyword.** A flat
   list of names carries neither the code a PRI encodes nor a selector reaching it, and
-  goal 2 draws the two as one fact. The canonical spelling losing to the one its domain
+  goal 3 draws the two as one fact. The canonical spelling losing to the one its domain
   writes, above, settles the rest: a configuration writes `info`, so RFC 5424's
   `Informational` stays the `severity` column, and the code and the keyword hold the
   two selector slots.
@@ -1258,7 +1259,7 @@ the Development section below, and who ships a register the four above then draw
   host with no separator. `misc.tld[se]` misses for it, which `todo.md` carries.
 - **`misc.tld` is a table of its own, and `misc.territory.tld` stays a column.** A
   `parent` demands a child for every parent row, so linking them would drop every root
-  zone row naming no territory, which is most of them, and goal 11 holds a sourced
+  zone row naming no territory, which is most of them, and goal 12 holds a sourced
   table whole. The loader refuses the link outright anyway: `tld` is a column of
   `misc.territory`, and a table may not be named like a column of its ancestor.
 - **`misc.territory` carries a currency code, it does not link to `misc.currency`.**

todo.md

@@ -7,7 +7,7 @@ Ordered as the releases that ship it.
 ### Comprehension, until the panel scores 7.0
 
 Nothing else ships while the score is under 7.0 — no feature, no category, no data —
-bar a security fix and a dependency bump, per README goal 14. This section is one
+bar a security fix and a dependency bump, per README goal 2. This section is one
 round, replayed: the `comprehension-panel` skill's nine-seat findings run at depth 1,
 a PR per item it names, then the run again, until the score passes. The run is the
 nine-seat one: the round is meant to buy architectural change, and the four-seat
@@ -50,7 +50,7 @@ This round, in order:
 ### Data
 
 Shape: T = table, t = template, c = choice. Read every factual list from a register
-by a `data-import/` script, as README goal 11 asks.
+by a `data-import/` script, as README goal 12 asks.
 
 - Add the remaining `misc` tables and templates, one row of the table below per chunk.
 - Read `misc.emoji` from the Unicode `emoji-test.txt` register, and `misc.car` from an
@@ -63,16 +63,16 @@ by a `data-import/` script, as README goal 11 asks.
   `municipality` as columns on `geo.SE.address` too.
 - Fill the 398 Swedish localities weighted 200 from SCB småorter.
 - Give `url` and `email` a path that draws only domains nobody can register, keeping
-  the wide set as the default, per goal 13: 17 of the 40 distinct ones shipped today
+  the wide set as the default, per goal 14: 17 of the 40 distinct ones shipped today
   sit on `.se`, `.nu`, `.io` and `.co`, which anyone may register, and only RFC 2606's
   `example.com`, `.net`, `.org`, `.test`, `.example`, `.invalid` and `.localhost`
   provably reach nothing.
-- Audit the rest of the shipped set against goal 13 and give each a never-reaching
+- Audit the rest of the shipped set against goal 14 and give each a never-reaching
   path where it lacks one: `phone` draws live PTS and NANP ranges, `bankgiro`,
   `plusgiro` and `routing` draw live prefixes.
 - Stop `misc.territory[EH].tld` rendering `.eh`, the one shipped TLD `misc.tld` does
   not hold: ISO 3166 reserves it for Western Sahara and the root zone has never been
-  delegated it, so no resolver answers for it and goal 2 promises otherwise.
+  delegated it, so no resolver answers for it and goal 3 promises otherwise.
 - Draw `en_US.phone`'s `exch` as a NANP central office code: `{int(100,999)}` renders
   a leading 1 in about an eighth of draws, which libphonenumber rejects, and
   `TestShippedUSPhone` proves the shape rather than the rule. Assert the rule with it.
@@ -91,7 +91,7 @@ by a `data-import/` script, as README goal 11 asks.
   beside the family: require the path step to reach a sibling category, and seed every
   draw group of the render from the outer selector's pins.
 - Read `email.local`'s and `username`'s handles from the shipped name tables, which
-  goal 11 asks for and the hand-written list they use today does not meet. Keep the
+  goal 12 asks for and the hand-written list they use today does not meet. Keep the
   handle shape: `username` shortens a surname to `ahl` or `sjo`, and the US one draws
   unisex given names, neither of which falls out of the tables unaided.
 - Decide whether `email.local` and `username` share one list: a reference between
@@ -177,7 +177,7 @@ by a `data-import/` script, as README goal 11 asks.
   path is `gitea.larvit.se/larvit/fejkdata`, a developer looking for a fake-data
   library searches GitHub and pkg.go.dev, and a module path is a major to change.
 - Decide whether `data/misc`'s 33 flat files gain a level before v1.0.0: a folder is a
-  path segment, so `misc/net/tld` is a rename a consumer pays for, and goal 12 promises
+  path segment, so `misc/net/tld` is a rename a consumer pays for, and goal 13 promises
   the directory keeps growing.
 - Decide whether `misc.browser` becomes a parent of `misc.useragent`, so
   `misc.browser[Chrome].useragent` resolves. Adding a `parent` after v0.1.0 breaks a