Repository navigation
Tracking: sequenced work plan for the Stage 1–3 roadmap #8
Description
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. Phases 0–2 are complete — the defect fixes landed via #9, character-level churn (#4) via #10, both hygiene items (F3, F4) are done, and #1's three-edition run and report closed 2026-08-28 (see the plan row). All phases are complete (0–5, closed 2026-08-28; #7 last, via QuantEcon/status-translations#12 with its first run green). The only remaining row is parked #3, waiting on an fr edition — this tracker is a close-out candidate.
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 — closed 2026-08-28; report merged as QuantEcon/project-translation#53, the overrides file landed via #12, state-file via #11, and the adjudication's one systematic catch via #13 |
| 3 | #2 | ✅ Engine-version strata — closed 2026-08-28 via #15; per-sync engine_model/engine_tool_version stamps from the state-file history, engine_strata totals in run.json; literal model: unknown kept distinct from unrecorded |
| 3 | #6 | ✅ Overwrite evidence to action-translation — closed 2026-08-28, filed as QuantEcon/action-translation#295 with the three-edition F2 table and example pairs |
| — | #14 | ✅ Prose-gate unpaired additions/deletions — closed 2026-08-28 via #16; non-prose unpaired lines route to code-or-markup, total pair count unchanged (at programming.zh-cn: additions 103→30, deletions 80→38) |
| 4 | #5 | ✅ PR-API channel — closed 2026-08-28 via #17; design note on the issue, optional collect-pr command outside the deterministic core, acceptance on programming.zh-cn (84 comments, 15 from closed-unmerged PRs) |
| 5 | #7 | ✅ Scheduled runs and artefact history — closed 2026-08-28; history lives in status-translations (QuantEcon/status-translations#12), first run green and independently reproducing the audited baseline; Lifecycle page filed as QuantEcon/status-translations#13 |
| 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.
Activity
mmcky commentedon Aug 25, 2026
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-stage1holds #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:
descriptionfields; 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.mmcky commentedon Aug 28, 2026
Closing 2026-08-28: every phase of this plan is delivered, three days after it was sequenced.
The ledger. Phase 0: defect fixes and hygiene (#9, F3/F4). Phase 1: character-level churn (#4 via #10). Phase 2: the three-edition run and first report (#1 via QuantEcon/project-translation#53, with the
state-filestrategy #11, the reviewed overrides #12, and the adjudication's sync-signature catch #13). Phase 3: engine-version strata (#2 via #15) and overwrite evidence to the engine (#6 via QuantEcon/action-translation#295). Off-path: prose-gated pairs (#14 via #16, filed from the adjudication). Phase 4: the PR-API channel (#5 via #17, design note on the issue). Phase 5: scheduled runs and artefact history (#7 via QuantEcon/status-translations#12, first run green and independently reproducing the audited baseline from CI).What remains, and where it lives. #3 (
source-difffor fr) stays open and parked by design —wp8-stage2milestone, native sub-issue of QuantEcon/project-translation#49 — waiting on an fr edition; its config guard fails loudly meanwhile. Ongoing operation needs no tracker: the monthly scan runs from status-translations (next firing the 3rd), history accumulates indata/textstrata/, and the Lifecycle page is QuantEcon/status-translations#13. The preserve-rule proposal sits with the engine as QuantEcon/action-translation#295.The plan table above is the authority on what happened and in which order; the milestones state stage membership, as their descriptions say.