major-revision-discipline

Major Revision — disciplina di risposta (tracked-changes)

Regole operative per gestire le Major Revision (R2/R3) di journal, dove un manoscritto tracked-changes + un documento di risposta strutturato vanno consegnati all'editor.

Provenienza: emerse dall'audit del paper JAMT-D-26-01185R1 (LSR/FDM stampi additivi, Springer IJAMT, deadline 2026-05-18), dove una baseline non validata come vero twin del PDF sottomesso ha compromesso la tracciabilità e forzato un REMEDIATION completo. Era una global rule always-on (~/.claude/rules/review-discipline.md); promossa a skill on-demand in S4 (anti-bloat, BL-002) — stessi trigger, caricata solo nei contesti di revisione.

The 10 rules

1. The submitted PDF is immutable ground truth. Whatever conversion/regeneration produces, the result must be a per-page semantic twin of the submitted PDF. The submitted PDF is what the reviewers actually read; anything else is a derivative.

2. Two-snapshot policy: M0 then M1.

   • M0 = baseline twin (zero changes, zero residual Word comments, unified bibliography, identical figures/tables in identical positions).
   • M1 = M0 + reviewer-driven inserts (tracked, colour-coded per reviewer). Never enter M1 without a signed-off M0. M1 inherits all M0 fixes; never patch M1 retroactively for M0 issues.

3. BASELINE_GROUND_TRUTH.md is mandatory before any conversion. Inventory verbatim from the submitted PDF: section/subsection list, figure captions in order, table captions in order, equation numbering, page-by-page mapping. Compare every artifact against this document.

4. Pre-process source files at the source. If the docx contains Word native comments, strip them at the XML level (<w:commentRangeStart/End>, comments*.xml) before pandoc. Do not patch the resulting .tex after the fact — re-running pandoc will regress the patch.

5. Patches are idempotent Python scripts in tools/. Never one-off manual edits. Each patch must:

   • Have a --dry-run flag.
   • Validate anchor uniqueness (abort if 0 or ≥2 matches).
   • Check for an idempotency marker before applying (so a re-run is a no-op).
   • Document its purpose, the reviewer comment it addresses, and the line/section it targets.

6. Anchor-based re-injection (3–5 token unique strings), never line numbers. Line numbers shift between iterations; anchors shift only when the text itself changes. The script must verify each anchor matches uniquely and abort otherwise.

7. Multimodal verification is mandatory for every M0 (and M1) iteration. Use Claude Read on 5–10 sample pages distributed across the manuscript, comparing submitted PDF vs current build. Convergence = 0 HIGH discrepancies + ≤2 LOW (cosmetic).

8. Companion docs are refreshed via script, never by hand. RESPONSE_TO_REVIEWERS.md, CHANGE_LEDGER.md, OPEN_POINTS_*.md, PROJECT.md must be re-generated/updated by ~/config_vsc/tools/update_doc_refs.py (absolute path — this skill is global, so a relative tools/ would mis-resolve against each project's own cwd) so that line/page numbers are always current. The script delegates ledger parsing to coauthor_utils.py and supports --dry-run. Manual edits drift silently.

9. Snapshot zip per milestone in source_tex/_backups/M{N}_descriptor_v{NNN}.zip. Include: tex sources, all PDFs built in that milestone, figures, bib, tools, companion docs. Snapshots are write-once; never overwrite, bump the version suffix.

10. Plan + plan snapshots in ~/.claude/plans/. The live plan is ~/.claude/plans/<name>.md; semantic milestones (M0_REMEDIATED, M1_REMEDIATED, M2_signoff) get a frozen copy <name>_M{N}.md so that the trajectory is reconstructible.

Reviewer colour map (changes package)

When a paper has multiple reviewers, distinguish them in the tracked PDF:

Author ID	Colour	Used for
vvRtwo	red	R2-only changes
vvRthree	blue	R3-only changes
vvCross	violet	Cross-reviewer (R2+R3 overlap)
pont	ForestGreen	Co-supervisor edits (Ponticelli)
arno	orange	Co-author edits (Arnò) or experimental dataholder

Never use underscores in author IDs (vv_r2 triggers math-mode subscripts in margin notes → TikZ failure). Use camelCase or run-on words.

Always escape # as \# inside comment={...} arguments (LaTeX parameter marker conflict).

Use markup= defaults, not markup=underlined — the underlined renderer uses TikZ paths that fail on long inline insertions in current TeX Live releases.

Block patterns

Three patterns coexist depending on content scope:

• Inline single-paragraph: \replaced[id=ID,comment={R2\#N: ...}]{NEW}{OLD} or \added[id=ID,comment={...}]{...}. Renders coloured + struck-through (deletion) in TRACKED, accepted/silent in CLEAN.
• Multi-paragraph blocks (with \SI{}, tables, figures, equations): wrap with comment delimiters

  % === ADDED [R2#N] (id=ID): description ===
  ...content...
  % === END ADDED [R2#N] ===
  

  Renders as plain body text in both modes; traceability lives in the source comments. Do NOT wrap floats inside \added{} — the changes package macro cannot accept paragraph-level content.
• Brand-new sections (entire \section{} or \subsection{} added in revision, like §4.3 Sensitivity, §5 Discussion, §6 Limitations): MUST be wrapped in the same multi-paragraph block delimiters so the colour-delta extractor and the Word-plugin master-prompt generator can detect them as Phase 3 ops:

  % === ADDED [R2#N] (id=ID): NEW Section §X.Y title ===
  \section{Title}\label{sec:label}
  ...full section content...
  % === END ADDED [R2#N] ===
  

  Discovered in JAMT-D-26-01185R1 R2 finalization (2026-04-27): §4.3/§5/§6 had only \reviewmark{} anchors without block delimiters → the master-prompt generator emitted 0 Phase 3 ops and the operator had to add them by hand. Always wrap.

TODO markers for blocked items

For items requiring external input (data from collaborators, lab measurements, expert judgement) that is not yet available, use inline green-bold TODO markers:

\textbf{\textcolor{ForestGreen}{[TODO Ponticelli/Arno: <action needed>]}}

These are intentionally visible in BOTH the TRACKED and the CLEAN PDF — they are an audit trail of what still must be resolved before EM submission. They survive the changes package's final mode because they are not \added macros.

Status tracking — DONE / OPEN / BLOCKED

Every reviewer comment and every tracked-changes block carries a status in the CHANGE_LEDGER.md. Three values, mutually exclusive:

Status	Meaning	Where it lives	Visible to reader?
DONE	Wording finalized, no external input required.	CHANGE_LEDGER.md Status column only. The block in the body is just colour-marked per-reviewer.	TRACKED PDF: coloured. CLEAN PDF: integrated as plain text. No badge.
OPEN	Best-estimate inserted but a co-author decision (typically the supervisor) is needed before submission.	CHANGE_LEDGER.md + inline [TODO <Co-author>: <decision needed>] green-bold marker in the body.	Both TRACKED and CLEAN PDFs show the green TODO inline.
BLOCKED	Best-estimate inserted but external data/measurement/quote is awaited (collaborator, lab, vendor, editing service).	CHANGE_LEDGER.md + inline [TODO <Source>: <data needed>] green-bold marker.	Both TRACKED and CLEAN PDFs show the green TODO inline.

Two places, two purposes:

• CHANGE_LEDGER.md is the dashboard: roll-up N DONE / N OPEN / N BLOCKED + per-block Status column + Blocker column naming the responsible item (D1/D2/D3/A1-A5 or equivalent IDs).
• The body marker is the in-text reminder: it sits exactly where the missing info will go, so the reader/editor never loses context.

Lifecycle:

1. New block inserted with best-estimate → status BLOCKED (data) or OPEN (decision) + green TODO marker inline.
2. External input arrives → replace the best-estimate, remove the inline TODO marker, flip status to DONE in the ledger.
3. Before EM submission, 0 OPEN / 0 BLOCKED is the gate. Any residual must be either resolved or explicitly waived in the cover letter.

Anti-pattern: do not use [TODO] markers for completed work as a "comment to coauthors". TODO markers are status badges, not annotations. Use % comment LaTeX comments for non-rendered notes.