Implement the state-file baseline strategy (#1)

[mmcky]

Implements the state-file baseline strategy, the precursor #1 needs before the state-file reading can be tried on programming.zh-cn. Part of the sequenced plan in #8 (Phase 2).

What it does

The translation moment becomes the first revision of the document's per-document state file (machine.state_dir/<name>.yml, renames followed) — the engine's own record that it created the translation — instead of the script-ratio heuristic. Three shapes observed in lecture-python-programming.zh-cn are handled:

Shape	Example	Reading
Document and state file land in one commit	25 lectures via translate init (93dfab0)	that commit
Adjacent single-file commits (doc, then state)	autodiff.md (5ca0651 + 2231b45, one second apart)	the last document revision not after the state file's creation
No state file	_admonition/gpu.md, hand-translated in #23	untranslated, logged; correctable via baseline.overrides

Config validation requires machine.state_dir when the strategy is selected, replacing the previous "planned but not implemented" hard error. baseline.overrides wins regardless of strategy, unchanged.

programming-zh-cn.yml adopts the strategy, with one override for the hand-translated gpu.md snippet.

Verification

Scanning lecture-python-programming.zh-cn @ 403f52a under both strategies yields identical translation moments for all 28 documents — the authoritative record validating the heuristic on the one corpus where both apply. Corpus results: 28/28 translated, composition ai-initial 83.3% / ai-sync 9.9% / ai-assisted 6.8% / human-editor 0.0%, review state 26 machine-only / 2 human-touched.

Full suite green locally, including the pinned intro.zh-cn regression (checkout at 0466562); new tests/test_baseline.py covers the same-commit, adjacent-commit, no-state-file and override cases on a synthetic engine-era repository built in the fixture.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements the state-file baseline strategy for determining a document’s translation moment based on the first revision of its per-document engine state file, and wires it into scanning/config/docs. This supports engine-managed repositories where the state file is the authoritative provenance record, while keeping baseline.overrides as the escape hatch.

Changes:

• Add state-file translation-moment strategy (translation_moment() / _state_file_moment()) and use it during scans.
• Update config validation to require machine.state_dir when baseline.strategy: state-file is selected.
• Add targeted tests and update documentation/reference config + changelog.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_units.py	Updates config-validation unit test for state-file requirements and adds a passing config case.
tests/test_baseline.py	New tests for state-file moments (same-commit, adjacent-commit, missing state file) and override precedence.
src/textstrata/scan.py	Introduces translation_moment() with state-file implementation and integrates it into scan().
src/textstrata/config.py	Enables state-file strategy and validates machine.state_dir when selected.
docs/method.md	Documents state-file strategy semantics and precedence with overrides.
docs/configuration.md	Documents configuration requirements for selecting state-file.
configs/quantecon/programming-zh-cn.yml	Switches reference config to baseline.strategy: state-file with an override for a hand-translated doc.
CHANGELOG.md	Notes the new state-file baseline strategy and its requirements.

Suppressed comments (1)

tests/test_baseline.py:91

• Same issue as above: the returned translation_date comes from git's %aI and is expected to be offset-formatted (e.g. +00:00), not necessarily Z.

    repo, shas = engine_repo
    cfg = make_cfg(repo, overrides={"lectures/c.md": shas["c_doc"][:7]})
    assert moment(cfg, repo, "lectures/c.md") == (shas["c_doc"], "2026-05-01T09:00:00Z")

---

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