From b088d4f075bdbab888b555dd49563b9dd138674c Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sat, 14 Nov 2026 10:51:11 +0100 Subject: [PATCH] Record the comprehension check: scoring run at fa8600f, overall 5.88; floor item 178 filed --- docs/comprehension-history.md | 44 +++++++++++++++++++++++++++++++++++ todo.md | 15 +++++++++++- 2 files changed, 58 insertions(+), 1 deletion(-) diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index f3f2a1f..958153b 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -1749,3 +1749,47 @@ Ruling: same |---|---|---|---|---|---| | Mid A | same | same | same | same | same | | Inherited architect | same | same | same | same | same | + +## 2026-11-14T09:49:34Z, PR #162 at fa8600f + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7 | 5 | 6 | 5 | 5.5 | +| Mid A | 7 | 5.5 | 6 | 5.5 | 6 | +| Maintainability senior | 7 | 5.5 | 6 | 5.5 | 6 | +| Inherited architect | 6 | 5.5 | 6 | 5.5 | 6 | +| Mean | 6.75 | 5.38 | 6.00 | 5.38 | 5.88 | + +Junior A, hardest first: + +- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: a forward and a backward sweep over three verdicts and four standings, whose case derivation lives only in the decision log +- Self-sufficiency: `src/markdown/emit/line-escaping.ts:99` `readBack`: up to three escape passes running the reader inside the writer, with no statement of why three suffice +- Locality: `src/markdown/emit/inline-line.ts:120` `settledLine`: a generic fallback loop whose state changes out of sight through the `LineFallbacks.carried` Set +- Locality: `src/markdown/inline-content.ts:255` `directiveMarkPieces` / `closeBracket`: a mutable `Scan` shared across eight or more piece kinds +- Shape: `src/markdown/emit/block-text.ts:109` `prefixedLine`: open, started and innermostQuote bookkeeping for lazy container prefixes + +Mid A, hardest first: + +- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding`: the only case analysis kept outside the code, in a locally coined vocabulary +- Locality: `src/markdown/emit/inline-line.ts:120` `settledLine`: fallbacks mutate the `carried` Set and `openingLinkAsDirective` in place, and the 32-pass cap's termination is only named +- Locality: `src/markdown/inline-content.ts:424` `closeBracket` / `applyClosing`: one mutable `Scan` shared by nine piece kinds in a 695-line file +- Locality: `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: a reference-keyed memo with take, ask and depth rebasing, and headroom kept across three types +- Shape: `src/markdown/portable/adf-to-portable-markdown.ts:126` `portableSequence`: whether a block is replaced turns on a reference comparison +- Locality: `src/markdown/parse/markdown-to-adf.ts:126` `directiveNode`: the parser refuses a directive through a hand-kept map that must agree with the emitter + +Maintainability senior, hardest first: + +- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: two coined vocabularies and two sweeps, with the correctness argument in the decision log +- Locality: `src/markdown/emit/line-escaping.ts:99` `readBack`: a fixpoint over escapes steered by a full re-parse, with per-character `Uint8Array` codes +- Shape: `src/markdown/emit/inline-line.ts:120` `settledLine`: a three-type-parameter loop for two consumers, the `carried` Set mutated by helpers away from it +- Navigation, Locality: `src/markdown/inline-content.ts:592` `pairingMarks`: scanner state written from several functions, in a file sharing its name with the 17-line `src/markdown/parse/inline-content.ts` +- Locality: `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: drop-on-read entries with rebased headroom, whose staleness rules need proving before touching `walkBlocks` +- Self-sufficiency: `src/markdown/emit/adf-to-markdown.ts:57` `writeMarkdown`: the writer's emit, re-parse, compare and fall back design is stated nowhere at its entry + +Inherited architect, would restructure first: + +- Navigation, Overall: `src/markdown/parse/inline-content.ts:10` `readInlineContent`: a 17-line shim sharing its name with the real reader at the markdown root, which no note explains, a wrong turn on the 3am path +- Locality: `src/markdown/emit/line-escaping.ts:99` `readBack`: the writer's correctness depends on reading back through the reader +- Shape: `src/adf/document.ts:38` `readAdfDocument`: the file holds the reader, the writer prechecks, the schema refusals and text merging +- Shape: `src/markdown/emit/adf-to-markdown.ts:57` `writeMarkdown`: the shared writer lives in a file whose name means the lossless one +- Self-sufficiency: `src/markdown/emit/unspellable-runs.ts:49` `pairVerdicts`: hands its reason to a decision title, as the 32-pass cap at `src/markdown/emit/inline-line.ts:61` does diff --git a/todo.md b/todo.md index 97817ba..655bc96 100644 --- a/todo.md +++ b/todo.md @@ -6,7 +6,7 @@ `Bar = 0.1` -`Next ID = 178` +`Next ID = 179` ## Items @@ -34,6 +34,7 @@ | 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 13.1 | | 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 10.5 | | 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 6.5 | +| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 6.2 | | 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 4.4 | | 9 | 0.5.0 | | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 3 | 2 | 1 | 4 | 6 | 3 by 6 | 2.1 | | 34 | 0.5.0 | | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 1 | 2 | 3 | 3 | 4 by 1 | 1.5 | @@ -250,6 +251,18 @@ Found by the principles audit of item 99, 2026-10-14. Technical principle: tests use random UUID v7 ids; `portable-markdown-to-adf.test.ts` already does. Found by the technical-principles audit of item 78, 2026-10-05. +### 178. Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own. + +The scoring run at fa8600f (PR #162) averaged 5.88 overall, under the 7.0 floor; Locality and Self-sufficiency scored lowest, at 5.38 each. Make these places, the ones every seat named, easier to read: + +- `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: the case analysis behind the two sweeps lives only in `docs/decisions.md`. State it in the types or the code, with one vocabulary. +- `src/markdown/emit/inline-line.ts:120` `settledLine`: fallbacks change the `carried` Set and `openingLinkAsDirective` out of sight. Make each pass's state an explicit value, with the 32-pass bound visible where it holds. +- `src/markdown/emit/line-escaping.ts:99` `readBack`: say in the code why three escape passes suffice. +- `src/markdown/inline-content.ts:255` and `:424` (`directiveMarkPieces`, `closeBracket`, `applyClosing`): one mutable `Scan` shared by nine piece kinds in a 695-line file. Split it by piece kind. +- `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: keep its take, ask and depth rebasing in one type. + +Keep every output byte-identical: the round-trip properties and the CommonMark suite must pass unchanged. + ### 58. Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts. Technical principle "Prefer a standalone Python script over a shell script": `AGENTS.md` ยง3 teaches