feat(ml): exercise-family blocks byte-identical to source, enforced in code; encode the ml#12 answers (glossary v0.5.0, rules 24 → 23, E2E scenario 28)

.dev/STATE.md

@@ -1,4 +1,4 @@
-verified: 2026-08-19
+verified: 2026-09-03
 
 # STATE
 

.dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md

@@ -1,3 +1,8 @@
+> **Superseded 2026-09-03** by `D-2026-09-03-ml-all-exercise-content-stays-english`: the editor's
+> answer on lecture-python-programming.ml#12 keeps every exercise-family block byte-identical to
+> the source until he rules on each exercise individually. Kept unedited below as the record of
+> the intermediate ruling.
+
 # Malayalam: exercise statements with mathematical content stay in English
 
 **Context**: The 2026-08-17 ruling (`D-2026-08-17-ml-math-heavy-sections-stay-english`) keeps

.dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md

@@ -0,0 +1,49 @@
+# Malayalam: all exercise content stays byte-identical English, pending per-exercise rulings
+
+**Context**: Two earlier rulings drew the translation-scope boundary inside exercises by the
+*kind* of content: `D-2026-08-17-ml-math-heavy-sections-stay-english` kept math-heavy Hint and
+Solution sections in English, and `D-2026-09-01-ml-exercise-statements-stay-english` extended
+that to exercise statements whose content is probabilistic or mathematical, with mixed
+sentences split clause by clause and pure-programming exercises translated normally (the rule
+text shipped in v0.27.0 said such an exercise "MUST NOT be left in English"). Both boundaries
+were the model's judgement call. Asked to confirm the 09-01 reading on
+lecture-python-programming.ml#12, the editor of record (@adisankarmt, 2026-09-01) answered
+that he has not made a final decision on exercises: "For now, please retain all
+exercise-related content in English and keep it byte-for-byte identical to the source. I will
+review each exercise individually and decide later which parts, if any, should be translated
+into Malayalam." This is a translation-*scope* change and a reversal of a two-day-old ruling,
+so it needs its own record. #promote
+
+**Decision**: Accepted by @mmcky, 2026-09-03. For `ml`, every `{exercise}`,
+`{exercise-start}…{exercise-end}`, `{hint}`, `{solution}` and `{solution-start}…{solution-end}`
+directive is copied verbatim from the English source — fence line, label, body and closing
+fence — until the editor rules on that exercise individually. This supersedes
+`D-2026-09-01-ml-exercise-statements-stay-english` and subsumes
+`D-2026-08-17-ml-math-heavy-sections-stay-english` for as long as it stands (the 08-17 reader
+argument is unchanged; its boundary is simply moot while everything in an exercise is English).
+Per-exercise decisions the editor later makes are carried in the edition repo as reviewed text
+and, if a pattern emerges, come back here as a new ruling.
+
+Because the rule now has no judgement boundary, it is encoded **deterministically**, not as a
+prompt instruction: a post-processing step restores the listed directive blocks from the
+source in both init and sync output for `ml`, and a diff-check fails an `ml` translation whose
+block differs from the source. The prompt keeps only a short statement of the scope so the
+translator does not waste tokens on text that will be overwritten; the v0.27.0 clause
+instructing the model to translate pure-programming exercises is removed. This is the first ml
+scope rule that is fully mechanical, and it is the shape #260 (W2, localisation becomes
+deterministic) and the #189 Phase 3 lint graduation ask for.
+
+**Consequences**: The ex5 "over-read" logged on #296 for the v0.27.0 regeneration arm was
+correct behaviour under this ruling and is withdrawn as a miss. Retention checks and the
+script-ratio band (#229 lineage) must treat an all-English exercise, hint or solution block as
+compliant, as the 08-17 and 09-01 records already required. The two merged `ml` lectures are
+restored to compliance by lecture-python-programming.ml#14 (`functions`: 4 of 10 blocks;
+`python_by_example`: 7 of 10); `matplotlib` (ml#13) was already compliant. The harness carried
+no exercise, hint or solution directive in any fixture, so the fixture suite gains one before
+the engine change is validated. Nothing here generalises beyond `ml`.
+
+**Refs**: issue #189 (Phase 2, round 2 follow-up), #296, #260,
+lecture-python-programming.ml#12 (the ruling), ml#14 (restoration), ml#7 lines 484, 515, 517,
+557–565, 626, `D-2026-09-01-ml-exercise-statements-stay-english`,
+`D-2026-08-17-ml-math-heavy-sections-stay-english`, QuantEcon/project-translation
+`reports/2026-09-01-ml-functions-review-disposition.md`.

.dev/log/2026-09-03-ml-round2-answers.md

@@ -0,0 +1,16 @@
+# 2026-09-03 — ml round-2 answers (ml#12) encoded; exercise scope goes deterministic
+
+**Trigger**: Adisankar answered QuantEcon/lecture-python-programming.ml#12 on 2026-09-01. Five of six word choices matched our guesses (*work* did not: he keeps the light-verb form `work ചെയ്യുന്നുണ്ടോ`); line 159 confirmed a typo; the font needs no change. His exercise answer reversed the two-day-old ruling: keep **all** exercise-related content English, byte-for-byte, until he decides per exercise.
+
+**Done**
+- `D-2026-09-03-ml-all-exercise-content-stays-english` (supersedes the 09-01 record, note atop it).
+- `src/verbatim-directives.ts` — nesting-aware extent walker (backtick/tilde/colon fences, literal bodies opaque, `PROSE_DIRECTIVES` now exported from typography.ts), `applyVerbatimDirectives` wired into sync-orchestrator (both seams), init and forward, each immediately before `checkStructuralParity`; `findVerbatimViolations` → `checkVerbatimDirectives` in diff-checks (optional `targetLanguage` on `runDeterministicDiffChecks`), surfaced in reviewer.ts as a `blocker` / `diff-check` finding — additive, no schemaVersion bump.
+- `ml` rules 24 → 23 (two scope rules → one verbatim statement; *For example* joins the connectives; `refer` calque named; headings byte-identical incl. possessives); glossary v0.5.0 (+5).
+- E2E scenario 28 `28-add-exercise-lecture` — first exercise-family directives in the suite; README + valid-prefix message updated.
+- Suite 1553 green, lint/format/dev-refs clean, `dist/` + `dist-action/` rebuilt.
+
+**Lecture side**: ml#14 restores functions (4/10 blocks) and python_by_example (7/10) to byte-identical English plus the typo; matplotlib (ml#13) was already compliant.
+
+**Withdrawn**: the ex5 "over-read" logged on #296 for the v0.27.0 arm — correct under the new ruling.
+
+**Next**: local-bundle validation against a scenario-28 harness PR on the `.ml` lane (expect the blocks byte-identical and the diff-check green), then PR, then release before round 4 is generated.

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- **Verbatim directive policy, enforced in code** (`src/verbatim-directives.ts`). For editions that keep a directive family byte-identical to the English source — the first is `ml`, whose editor of record ruled on lecture-python-programming.ml#12 that every `{exercise}`, `{exercise-start}…{exercise-end}`, `{hint}`, `{solution}` and `{solution-start}…{solution-end}` block stays in English until he rules on each exercise individually — the blocks are restored from the source after translation on all three write paths (sync, `translate init`, `translate forward`), immediately before the structural-parity guard so parity checks the bytes that are written. Block extents come from a nesting-aware fence walk (backtick, tilde and colon fences; literal bodies such as code cells are opaque), blocks pair by position, and a differing block sequence is left untouched and logged rather than guessed. A rule with no judgement boundary does not belong to the model. Decision record `D-2026-09-03-ml-all-exercise-content-stays-english` supersedes `D-2026-09-01-ml-exercise-statements-stay-english`.
+- **Review diff-check `verbatimDirectives`** (`diff-checks.ts`, `reviewer.ts`): for a policy language, a target block that is not byte-identical to its source counterpart surfaces as a `blocker` finding in the gating `diff-check` category, routing the PR to the editor. It is not one of the four published `diffChecks` booleans, so the verdict schema is unchanged; `runDeterministicDiffChecks` gains an optional `targetLanguage` parameter.
+- **E2E scenario 28** (`28-add-exercise-lecture`): a source change that adds an Exercises section with `{exercise-start}`/`{solution-start}` blocks and a `{hint}` — the first exercise-family directives in the harness fixture suite. On the `.ml` lane the sync output must carry those blocks byte-identical; on `.zh-cn` and `.fa` they translate as before.
+
+### Changed
+
+- **`ml` rules 24 → 23, glossary v0.4.0 → v0.5.0** from the editor's ml#12 answers (2026-09-01): the two exercise-scope rules (09-01 statements, 08-17 math-heavy Hint/Solution) are replaced by one statement of the verbatim policy; sentence-initial *For example,* joins the English-retained discourse connectives (not ഉദാഹരണത്തിന്); the light-verb rule names the `refer` calque (never സൂചിപ്പിക്കുന്നു, seen on both v0.27.0 regeneration draws); the heading rule now says byte-identical including possessives (the `Matplotlib's Split Personality` → `Matplotlib-യുടെ` miss on ml#13). Glossary pins: *already*, *example* / *examples*, *name* (the noun; the act of naming stays പേര്), *work* (light-verb form). The ex5 "over-read" logged on #296 for the v0.27.0 arm was correct behaviour under the new ruling and is withdrawn.
+
 ## [0.27.0] - 2026-09-01
 
 ### Added