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. 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.

[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.

[mmcky]

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-file strategy #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-diff for fr) stays open and parked by design — wp8-stage2 milestone, 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 in data/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.