Tracking: sequenced work plan for the Stage 1–3 roadmap

[quantecon-services]

Repository: QuantEcon/textstrata
Snapshot: 2026-08-25, main @ 2bef0c1
Source: repository audit of 2026-08-25 (all open issues reviewed against the code at the snapshot SHA)
Part of: QuantEcon/project-translation#49 (lifecycle metrics)

Background

An audit on 2026-08-25 reviewed all seven open issues against the code at main @ 2bef0c1. The tracker is an accurate roadmap — nothing filed is already done, and nothing done is untracked — but six of the seven issues hang off one critical path (#1, the first three-edition run), and the audit found two code-level defects worth fixing before that run plus two hygiene gaps. This issue captures the recommended order.

Where we stand

CI green on main, including the regression job reproducing the 2026-08-04 study on the pinned lecture-intro.zh-cn checkout; the remaining roadmap issues are each a native sub-issue of QuantEcon/project-translation#49 and now carry a wp8-stage* milestone. Phase 0 and phase 1 are complete — the defect fixes landed via #9, character-level churn (#4) via #10, and both hygiene items (F3, F4) are done. The critical path is now #1.

Findings

	Finding	Severity	Status
F1	baseline.strategy is accepted but never read — state-file (which #1 says to try on programming.zh-cn) or any typo silently scans as script-jump (src/textstrata/config.py, load_config; contrast the hard error for prose.strategy: source-diff)	High — silently wrong baselines for #1	✅ Fixed in #9 (merged)
F2	README ("Churn is also reported in changed characters") and docs/method.md ("churn is also available in changed characters from the pairs") claim a metric that is not implemented — no artefact carries a character count; #4 tracks the work	Medium — docs mislead	✅ Fixed in #9 (merged); the metric itself landed in #10
F3	Bare cross-repo references — #22 in #1, #2, #5 and #276 in #6 — resolve against this repo's own numbering and would mislink once those numbers exist here	Low	✅ Done 2026-08-25 — rewritten to QuantEcon/project-translation#22 and QuantEcon/action-translation#276, both targets read and verified to be the cited issues
F4	Within this repo the Stage 1/2/3 structure and the inter-issue dependencies (#2 → #1, #6 → #1) lived only in prose — no labels or milestones	Low	✅ Done 2026-08-25 — wp8-stage1/2/3 milestones assigned (below); milestones were chosen over labels to keep the label set QEP-2-clean

Work plan

Phase	Issue	Work item
0	#9	✅ Land the defect fixes: F1 validation, F2 doc alignment, plus lint fixes for rules ruff 0.15 now enforces (CI installs ruff unpinned) — merged 2026-08-25
0	—	✅ Hygiene: cross-repo references qualified in #1, #2, #5, #6 (F3); wp8-stage* milestones assigned (F4) — 2026-08-25
1	#4	✅ Character-level churn alongside line counts — landed via #10, merged 2026-08-25 (regression verified against the pinned checkout)
2	#1	Three-edition run and first report — the critical path; needs an overrides file (or an ai-assisted reading) for python.zh-cn's 12 probable whole-file AI passes
3	#2	Engine-version strata from .translate/state — design depends on what #1 finds in the state files (multi-revision records, model: unknown)
3	#6	Overwrite evidence to action-translation — pure write-up; overwrites.json already carries per-sync prior-tier counts and example pairs
4	#5	PR-API channel — after a design note keeping it an optional collector outside the deterministic core (AGENTS.md: no network in the scan)
5	#7	Scheduled runs and artefact history — after the method is validated across editions; decide first whether history lives in textstrata, status-translations, or a data repo
parked	#3	source-diff prose strategy for fr — Stage 2; correctly hard-guarded in config validation, wait for an fr edition

Stage milestones

Taken from each issue's own text — the shared footer marks all of them as part of #49's programme Stage 1, while #3 and #7 declare their own later stages. This tracker itself is deliberately unmilestoned: it spans all three.

Milestone	Issues
wp8-stage1	#1, #2, #5, #6
wp8-stage2	#3
wp8-stage3	#7

Sequencing

Phase 0 protected #1's numbers: without F1's fix, trying the state-file strategy on programming.zh-cn silently produced script-jump baselines. #4 landed before #1 so human churn can be reported in both units from the first report. #2 and #6 unblock the moment #1's artefacts exist — #6 needs no code at all. #5 and #7 are independent of each other but both sensibly follow #1; scheduling before the method is validated across editions would automate unvalidated numbers.

What does not need to change

The core scan and tier precedence (pinned by the regression test); #3's config guard, which already fails loudly; the overwrites.json format, which is sufficient evidence for #6 as-is.

Notes

This issue deliberately does not claim the roadmap issues as native sub-issues: GitHub allows one parent per issue and they already belong to QuantEcon/project-translation#49. This tracker is the sequencing companion inside textstrata; tick the plan rows here as the referenced issues close.

The repo has not adopted the QEP-2 label set (no custom labels exist), so this issue is filed unlabelled.

[mmcky]

Note on F4, and the milestone descriptions (2026-08-25)

F4 named two things that "lived only in prose": the Stage 1/2/3 structure and the inter-issue dependencies (#2 → #1, #6 → #1). The wp8-stage* milestones encoded the first. The second is still prose — it lives in the Sequencing paragraph above and nowhere machine-readable. Milestones state membership; they do not state order. Worth a small edit to F4's status line if you want that table to stay precise.

The distinction is not academic here, because the two axes in this plan genuinely cross: the milestones mirror QuantEcon/project-translation#49's programme stages, while this plan's own sequencing is Phase 0–5, so wp8-stage1 holds #1, #2, #5 and #6 — phases 2, 3, 4 and 3 — in no stated order.

Recording it because this instance became the basis of a proposed org-wide convention (QuantEcon/skills#55), and the review there turned on exactly this point. Nothing about the plan itself needs to change.

Two small things done rather than proposed:

• The three milestones had empty description fields; each now names the owning programme and points at this issue as the authority on order. That makes the milestone list self-describing without the name having to carry ownership, which is one of the open questions on Idea: Convention for use of milestones when building work plans skills#55.
• If you want the two dependency edges machine-readable, GitHub's native issue dependencies express them directly and need no naming convention. The 2026-08-23 org audit quoted in Discussion: a QEP for work-plan tracking issues — genres, the body/comment discipline, and succession qeps#15 measured 0 of 99 tracker-shaped issues using them, so this would be the first — entirely optional, and a plan-table row is a lighter edit.