# Implementation Plan: Review handoff and approved-translation capture

## Approach

Most of this specification is already met, and the honest plan says so rather than
rebuilding it.

Capture is done. `harvest-tm.mjs` refuses a whole-corpus harvest and exits non-zero
(AC-4), `--pages` scopes a capture to the pages a reviewer named (AC-3), `--as-of` pins
it to the revision they actually read, and four cases in `selftest.mjs` cover
supersession, including that a superseded record is reported rather than dropped
(AC-5). FR-005 and FR-006 need nothing.

What is missing is the handoff itself. FR-003 requires a proposal stating the source
content changed, the authority behind each term decision, the coverage achieved and
every escalated question; FR-004 requires observed source defects to be reported and
not corrected. Nothing assembles any of that today, which is why every merge request
in this project so far was written by hand.

So: one generator that turns a translation run into a proposal. It consumes what the
writer and the harness already produce — resolved counts from spec 004, per-segment
provenance and escalations from spec 005 — and emits the description. Nothing new is
computed, because anything the generator worked out for itself would be a second
opinion that could disagree with the run it is describing.

AC-1 is satisfied by construction rather than by code. The generator writes a file and
stops. Nothing in `.l10n-sync/` has ever called a forge API, and adding that capability
in order to then restrain it would be the wrong shape: a tool that cannot merge needs
no rule against merging.

FR-004 is a passthrough. Source defects are observed by a human or by a gate, and the
generator carries them into the proposal under their own heading so they are not lost
between noticing and reporting. It does not detect them and must not, since §9 keeps
English fixes with the docs team.

## Rollback

The generator writes one markdown file outside the published tree and changes nothing
else. Deleting the file is the rollback.

## Appendix

### Alternatives considered

**Opening the merge request directly.** Rejected. It would mean credentials and an API
client in a toolchain that currently has neither, to automate the one step a human
should take knowingly. Writing the description is the laborious part; clicking merge is
not.

**Recomputing coverage inside the generator.** Rejected. Two implementations of the
same number eventually disagree, and the proposal would then describe a run that did
not happen.

**Emitting a template for a human to fill in.** Rejected. A template with gaps is how
the authority behind a term decision goes unrecorded, which is the thing AC-2 exists to
prevent.