Work plan: suggested order for the post-review backlog

[mmcky]

Suggested sequence for the work left after the 2026-07-15 review round, with the reasoning for the order. Not a new roadmap — PLAN.md still holds the detail; this is what to do first and why, which PLAN deliberately doesn't say.

How this is ordered

Three rules, applied in this priority:

1. External clocks first. Only one item has a deadline someone else controls.
2. Detection before repair. Today's whole finding was that failures produce success-shaped artifacts. Fixing five silent bugs without a check that would catch the sixth is worse value than building the check.
3. Shared foundations before things that need them. Several items land once if sequenced, six times if not.

Remaining PLAN state, for calibration: Phase 1 8 todo / 2×[H] · Phase 2 14 / 4×[H] · Phase 3 19 / 3×[H] · Phase 4 9 · Phase 5 9 / 1×[H] · Phase 6 12 · Phase 7 8 · Phase 8 10.

---

1 — #89 node24 + @actions/* majors · S–M · do first

The only item with someone else's clock: GitHub is already force-running the action on Node 24 while action.yml declares node20, on every production run. It also carries the last open prod advisories (undici, only clearable via the majors), and it forces a dist-action/ rebuild — so it should not be split across releases.

Sequence it first because it is independent of everything below and gets less pleasant the longer the runtime divergence runs.

Validation caveat: src/index.ts is at 0% coverage, so the suite will not catch an @actions/* API break. Validate with the e2e harness (26 scenarios × 2 languages) — which is trustworthy as of #86/#87, and wasn't before. Pin its ref: to the candidate.

2 — Finish Phase 1 · S · same release as #89

Seven small items, mostly one-liners, all high-confidence: runRebase posting success on no-op early returns, context.sha vs merge_commit_sha on the primary sync path, \translate-resync zh failing open to all languages, the @anthropic-ai/sdk bump, CHANGELOG [Unreleased].

Plus Phase 1.5 — rebase input-validation hardening [H], the one security item in the backlog. It should land before #66 documents the metadata as a public contract.

Ship 1+2 together as v0.17.0 (the @actions/* majors make it a minor, not a patch).

3 — Phase 2: parser & validation correctness · L · the main event

The highest-leverage work in the backlog, and the reason to resist doing #90 first. It delivers four things at once:

• Translator drops MyST label anchors like (label)= before headings #65 — (label)= anchors dropped before headings. Known production breakage (broke a zh-cn build).
• Fence-aware parseSections — ## inside a code cell is currently parsed as a heading.
• The round-trip invariant test (reconstruct(parse(doc)) === doc) — this is the detection layer. It catches three of Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90's five defects as a class, and it would have caught the typography bug before it shipped.
• A real validateMyST — today it validates nothing (parseSections never throws, so the gates can't fire). Replacing it pays out three more times: it's the structural veto auto-merge needs (FUTURE 1), the basis of the No test set for model upgrades — v0.16.0 shipped a model change unmeasured #82 deterministic eval, and the check that makes the next unseen MyST construct a loud failure instead of silent corruption.

Do this before #90. Patching #90's five defects individually leaves you with five fixes and no way to catch the sixth — and there will be a sixth; there have been five already (#5, #6/#40, #49, #50/#54, #65, and the typography bug makes six).

4 — #90 remainder + canonicalizeHeading() · M

Whatever Phase 2's round-trip test doesn't cover:

• canonicalizeHeading() (REVIEW §7.6 R12) — one function used at every heading-map write and lookup site. Fixes Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90.1 (role-bearing headings never match, so sections get re-translated and human refinements discarded) and Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90.4 (heading level changes) structurally rather than site-by-site. Also settles docs: heading-maps.md documents a key format the action has never written #91's question of what a key actually is.
• Fail-closed content fetching (Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90.3) — fetchAllFileContents returns {files, errors}; fetch errors get treated like processing errors. No happy-path change.
• Silent data loss in the sync merge path — five ways translations vanish while the run reports success #90.5 frontmatter scalar re-typing.

5 — Phase 6: one LLM client, one parser, one state module · M–L · the multiplier

Not glamorous, but it's the precondition for the two best remaining ideas landing once instead of six times:

• R8 structured outputs — Sonnet 5 supports output_config.format. Deletes three defect classes at a stroke: the 3-strategy JSON parsing, the retry-on-parse-failure loop (3 full-price calls on persistent bad JSON), and the NaN-verdict bug (Phase 4). Cheapest permanent fix for all three.
• R9 prompt caching — the static prefix (rules + 357-term glossary ≈ 15K tokens) is resent at full price on every call. Section-based sync makes many calls per file inside the 5-minute TTL → cache reads at ~0.1×.

The evidence that Phase 6 matters isn't theoretical: CRLF was fixed in pr-creator but not reviewer; pagination in rebase but not sync; overloaded retry in the translator but nowhere else. Each of those was one bug fixed in one of several copies. #83 had to fix the same stop_reason guard in five places.

6 — Then, roughly in this order

	why here
Phase 4 (action robustness)	NaN verdicts largely fall out of R8; the rest is per-file review evaluation and rebase 409 retry (pairs with #92)
#92 PR-creation timeout	small; do with Phase 4's 409 retry — same "check the resulting state, don't trust the response" fix
#82 / R10 deterministic eval	after Phase 2 — it reuses Phase 2's validateMyST checks; building it first means building them twice
Phase 5 (test debt)	index.ts 0%, 32 fake tests in translator.test.ts, coverage threshold. Raise it opportunistically while touching things above
Phase 3 (CLI state)	19 items but all CLI-side; no production translation depends on it
Phase 7 / 8	docs remainder + issue gardening. Phase 8 is ~10 gh issue close with rationales already written in PLAN — genuinely an hour
#91 docs	minutes; do it alongside #4's canonicalizeHeading so the docs describe the settled answer

Cheap wins, any time

• Phase 8 gardening — ~10 issues closeable with pre-written rationale. Highest tidiness-per-minute in the backlog.
• R11 release automation — today's release needed: move 3 tags, bump 4 files, reconcile STATE, and I still left Next stale until Copilot caught it. A script or checklist-issue template would have prevented the v0-stale-for-9-releases bug outright.

What I'd explicitly not do yet

• ARCHITECTURE Q1 (repo topology) and Q2 (mystmd migration) — both correctly parked on external triggers; nothing today moved them.
• FUTURE 1 auto-merge — wants Phase 2's structural veto and Phase 4's review fixes first. It's the biggest throughput win available, and it's gated on exactly the work above.
• R2/R4 (state consolidation) — real, but only pays off when rebase state or a second consumer forces it. feat: document translation-sync-metadata as a stable, versioned contract for downstream tooling #66 is the trigger.

The through-line

Every defect fixed today, in the action and the harness, was one shape: the failure path produced a success-shaped artifact. Truncated translations committed as complete; backward analysis calling a truncated file clean; fetch failures dropping files under a green check; a partial eval reporting "25 passed, 0 failed"; a stale rubric confidently marking correct output down; reports silently never committed; a lint gate covering 41% of the code; v0 cheerfully serving year-old code.

The ordering above is mostly a bet that detection beats repair — Phase 2's round-trip test and a real validateMyST are worth more than any five individual fixes, because they're what makes the next one loud.

Refs: REVIEW-FABLE5-2026-07-15.md · PLAN.md · #89 #90 #91 #92 #81 #82 #65 #66

[mmcky]

Two field observations from the intro.zh-cn drift-recovery wave (2026-07-18, v0.17.0) that belong to items already in this plan:

Fence-aware parseSections (item 3) — intro_supply_demand.md was classified SOURCE_AHEAD by structural section count, yet two independent LLM triages (status --check-sync and forward's stage-1) both judged it complete and i18n-only, and manual inspection agrees. The phantom section-count divergence is consistent with a ## inside a fenced block being counted as a heading — a live false-positive from the parser gap this item fixes, and it put the file into a resync wave it didn't need to be in (harmless here only because forward's triage then skipped it).

Triage stability (relevant to #82's test-set) — lp_intro.md got opposite verdicts from two triage prompts in the same hour: status --check-sync flagged wholesale divergence (OR-Tools vs the source's SciPy rewrite), while backward's stage-1 said "file is in sync, no suggestions". Single-run LLM triage variance is real at exactly the moment it steers whether content is analysed or skipped; worth a stability metric in whatever eval harness #82 grows (program-side tracker: QuantEcon/project-translation#11).

[mmcky]

Status 2026-07-22: the pre-Phase-2 queue is empty — Phase 2 is next, and today sharpened its case.

Landed since the last update, in this plan's terms: item 4's defect-2 half is resolved (#137, removal-with-visibility on the 211-pair estate-scan evidence; translation.additions shelved with the decision record on #90 — the co-design question that would have gated Phase 2 is settled in favour of current reconstruction semantics), and the #107 measurement this plan wanted before more prompt work ran and closed the issue: enumerated localisation classes survive byte-for-byte; the residual class got a deterministic pin + verify guard rather than more prose (#140). That wave also seeded #82's first metric (details there). v0.21.0 shipped it all to the estate.

Three fresh exhibits for Phase 2 specifically:

1. The model-preamble leak (fix(resync): pin target-local data reads and strip model preamble — verify both, fail loudly #140's second fix): reasoning prose before the document's frontmatter produced a written file with two frontmatter blocks — invisible to the structural parity guard because prose carries no directives or anchors. A real validateMyST ("exactly one frontmatter block, at position 0") catches this class wholesale instead of per-shape.
2. Guard scope generally: three write-path defects have now each needed a bespoke deterministic check (structural tokens, pinned reads, embedded frontmatter). They are all shadows of the missing document-level invariant this plan's item 3 names.
3. The fence walk exists in four copies (structural-parity, target-local-reads, forward's frontmatter detector, plus the parser's own logic) — living proof of the Phase 6 duplication argument, and the first thing Phase 2's shared parsing utilities should consolidate.

Constraint carried forward unchanged: Phase 2's machinery lands in Jest-loadable modules, not index.ts. #120's triage is closed as executed; this issue is the plan of record.

[mmcky]

The 2026-07-23 technical-debt audit produced a larger sequenced plan that overlaps this one: 139 verified findings ordered into Wave 1 (11 PRs, ~129h), Wave 2 (8 steps, ~22-28 days) and a trigger-gated Wave 3, now tracked in the Technical debt — 2026-07 audit milestone and #177.

Worth recording that this issue's three ordering rules held up independently. "Detection before repair" is exactly why the audit's plan puts #158 (type-check the test suite) first and alone, and why #159's four-line parity guard ships before the refactor that would generalise it. "Shared foundations before things that need them" is the whole shape of Wave 2's dependency order.

Where the audit differs: it ranks on (recurring cost × likelihood) ÷ stopgap effort rather than on severity, which moves several low-severity items with two-line fixes near the top.

Leaving this open — the PLAN-state calibration here is still the better summary of phase-level progress.