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)

[mmcky]

Encodes the editor's answers on QuantEcon/lecture-python-programming.ml#12 (2026-09-01) — the items #296 held back — and, larger than expected, his exercise ruling, which reverses the 09-01 scope rule shipped in v0.27.0: every exercise-family block stays byte-identical to the English source until he rules on each exercise individually. Decision record D-2026-09-03-ml-all-exercise-content-stays-english (supersedes D-2026-09-01-ml-exercise-statements-stay-english, note atop it).

Why in code, not prompt

The v0.27.0 rule told the model that a pure-programming exercise "MUST NOT be left in English"; the editor now wants the opposite, with no judgement boundary at all. A rule with no boundary is a copy step. src/verbatim-directives.ts locates {exercise}, {exercise-start}…{exercise-end}, {hint}, {solution} and {solution-start}…{solution-end} as outermost regions with a nesting-aware fence walk (backtick, tilde and colon fences; literal bodies such as code cells are opaque, reusing typography's PROSE_DIRECTIVES, now exported) and restores them from the source for policy languages (ml, a Map like typography's rule table). Blocks pair by position; a differing block sequence is left untouched and logged rather than guessed. It runs on all three write paths — sync-orchestrator (both seams), translate init, translate forward — immediately before checkStructuralParity, so parity checks the bytes that are written. This is the first fully mechanical ml scope rule, the shape #260 (W2) and the #189 Phase 3 graduation ask for.

Review side

checkVerbatimDirectives in diff-checks.ts, carried by runDeterministicDiffChecks through a new optional targetLanguage parameter (present only for policy languages). A divergent block surfaces in reviewer.ts as a blocker finding in the gating diff-check category, so the PR routes to the editor. It is deliberately not a fifth DIFF_CHECK_NAMES entry: the verdict schema and the diff score divisor are unchanged.

The held items

Item	Encoding
For example, (Q1)	joins the English-retained discourse connectives; not ഉദാഹരണത്തിന്
example(s) (Q2), already (Q3), name (Q5), work (Q4)	glossary v0.5.0 pins (82 terms); name is the noun only — the act of naming stays പേര്; work keeps the light-verb form work ചെയ്യുന്നുണ്ടോ
refer calque (both v0.27.0 draws)	named in the light-verb rule: never സൂചിപ്പിക്കുന്നു
heading possessive miss (ml#13)	heading rule: byte-identical including possessives and punctuation
exercise scope	the 09-01 and 08-17 rules replaced by one verbatim statement (rules 24 → 23)

The ex5 "over-read" logged on #296 for the v0.27.0 regeneration arm was correct behaviour under the new ruling and is withdrawn.

Harness

The fixture suite carried no exercise, hint or solution directive anywhere, so nothing could exercise this end-to-end. Scenario 28 (28-add-exercise-lecture) appends an Exercises section with {exercise-start}/{hint}/{solution-start} blocks to lecture.md; on the .ml lane the sync output must carry them byte-identical, on .zh-cn/.fa they translate as before. Validation record for this PR follows in a comment (local bundle against a scenario-28 harness PR).

Lecture side

QuantEcon/lecture-python-programming.ml#14 restores functions (4 of 10 blocks) and python_by_example (7 of 10) to byte-identical English plus the line-159 typo; matplotlib (ml#13) was already compliant.

Suite 1553 green; lint, format and dev-ref checks clean; dist-action/ rebuilt.

Refs: #296, #189, #260. Supersedes the exercise half of #297's encoding.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

There are a few concrete maintainability/documentation issues in the new/modified code paths (notably misattached JSDoc and forward-compat gaps) that should be corrected before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR codifies a deterministic “verbatim exercise-family” policy for Malayalam (ml) by restoring exercise/hint/solution directive blocks byte-identically from the English source on all write paths, and by adding a review-time diff-check that escalates divergences as blocking findings. It also encodes the editor’s round-2 answers by updating the Malayalam glossary/rules and extends the E2E harness with a new scenario covering exercise directives.

Changes:

• Add src/verbatim-directives.ts to extract/restore exercise-family directive regions and wire it into sync/init/forward immediately before structural parity checks.
• Add deterministic review support (checkVerbatimDirectives) gated by an optional targetLanguage parameter and surface violations as blocker findings in reviewer.ts without changing the published verdict schema.
• Update ml language rules + glossary to v0.5.0, add harness scenario 28, update docs/changelog/decision log, and rebuild dist-action/.

File summaries

File	Description
tool-test-action-on-github/test-action-on-github.sh	Adds scenario 28 and updates scenario prefix validation/help text.
tool-test-action-on-github/test-action-on-github-data/28-add-exercise-lecture.md	New fixture that introduces exercise/hint/solution directives to validate verbatim behavior.
tool-test-action-on-github/README.md	Documents the new 28th scenario and updates scenario counts.
src/verbatim-directives.ts	Implements extraction, restoration, and violation detection for exercise-family verbatim blocks.
src/typography.ts	Exports PROSE_DIRECTIVES so verbatim extraction can reuse the directive classification logic.
src/sync-orchestrator.ts	Applies verbatim restoration on sync write paths before structural parity checks.
src/reviewer.ts	Passes targetLanguage into deterministic diff checks and escalates verbatim violations as blocking findings.
src/language-config.ts	Updates Malayalam rule set (24→23), folds in ml#12 answers, and replaces prior exercise-scope rule with verbatim policy statement.
src/diff-checks.ts	Adds optional verbatimDirectives deterministic check (enabled only for policy languages).
src/cli/commands/init.ts	Applies verbatim restoration in translate init before structural parity.
src/cli/commands/forward.ts	Applies verbatim restoration in forward resync before structural parity.
src/tests/verbatim-directives.test.ts	New tests covering extraction/restoration and deterministic diff-check wiring.
src/tests/language-config.test.ts	Updates assertions to match the new ml rules and removed prior scope ruling.
glossary/ml.json	Bumps glossary to v0.5.0 and adds the editor-answered pins (already/example(s)/name/work).
docs/developer/architecture.md	Registers the new module in the architecture map.
dist-action/index.js	Updates the committed action bundle to include the new verbatim policy logic and reviewer changes.
CHANGELOG.md	Documents the new deterministic verbatim policy, new diff-check behavior, and scenario 28.
.dev/STATE.md	Updates verified date to 2026-09-03.
.dev/log/2026-09-03-ml-round2-answers.md	New dev log entry recording the encoded ml#12 answers and deterministic scope change.
.dev/decisions/D-2026-09-03-ml-all-exercise-content-stays-english.md	New decision record superseding prior exercise-scope rulings and specifying deterministic enforcement.
.dev/decisions/D-2026-09-01-ml-exercise-statements-stay-english.md	Adds a superseded notice pointing to the new 2026-09-03 decision record.

Review details

• Files reviewed: 21/22 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[mmcky]

Harness validation (local bundle from 02f423c, per the unreleased-code recipe). The fixture suite had no exercise-family directive, so scenario 28 was opened by hand as QuantEcon/test-translation-sync#803 (unlabelled, so no @v0 workflow fired) and the bundle driven against it.

Step	Result
Sync, .ml lane, section-based path (## Exercises detected as ADDED)	QuantEcon/test-translation-sync.ml#102 — both blocks ({exercise-start}…{exercise-end}, {solution-start}…{solution-end}, hint nested) byte-identical to the source (11/11 and 16/16 lines); the model's own output was already compliant under the new rule, so the restore step had nothing to replace
Review, positive (head 8fcac27)	PASS, auto-merge; verbatimDirectives present and passing
Review, negative — one hint line inside the exercise block hand-translated to Malayalam (head e19c04f)	deterministic check failed: {exercise-start} block at target line 189 is not byte-identical to the source block at line 179 → blocker finding in the gating diff-check category → recommendation editor (score band still PASS, as designed: the finding routes, the schema is unchanged)
Production reviewer at @v0 (v0.27.0) on the same PR	PASS / auto-merge on both heads — i.e. today's release cannot see this class; this PR is what adds it

Two recipe notes for .dev/: the bundle needs GITHUB_SHA set to the PR head (with it unset it reads the default branch, reports the file as new and dies on "Document must have a # title heading"), and the PR API lags a push by a few seconds — verify pulls/N head.sha before driving a review, or it reviews the previous head (first negative run did exactly that and passed vacuously).

Release gate at the tag will run 28 × 3 = 84 sync runs.