Sync Submission

Sync Submission

Keep the canonical manuscript and journal-specific submission packages from drifting apart. Treat submission/{journal}/ as derived output and record whether it is current, stale, or frozen.

Inputs

1. Project root containing project.yaml, or a direct canonical manuscript path.
2. Journal short name, e.g. chest, ryai, academic_radiology.
3. Optional mode:
   • audit: compare existing submission against canonical source.
   • build: copy canonical source and optional declared final artifacts, preserving file bytes, and write metadata.
   • freeze: freeze the chosen byte snapshot with its available check context (not submission approval).

Deterministic Script

python "${CLAUDE_SKILL_DIR}/scripts/sync_submission.py" audit --project-root . --journal chest
python "${CLAUDE_SKILL_DIR}/scripts/sync_submission.py" build --project-root . --journal chest
python "${CLAUDE_SKILL_DIR}/scripts/sync_submission.py" freeze --project-root . --journal chest --status submitted

For double-blind journals, sweep author identifiers across all upload artifacts:

python "${CLAUDE_SKILL_DIR}/scripts/blind_sweep.py" \
  --registry _shared/authors/author_registry.yaml \
  --files submission/{journal}/supplementary/*.md submission/{journal}/cover_letter.md \
  --backup-dir .cache/blind_sweep_backup

The registry is a project-local YAML mapping author identifiers (full names, native scripts, initials with/without periods, email, ORCID) to role labels (e.g., "Reviewer 1"); schema in scripts/author_registry_example.yaml. Never commit a populated registry to a public repository, because it lists the authors' identities — keep it next to the manuscript.

Output Contract

For a complete bundle, run the existing renderers first, then build --bundle-spec bundle.json. The declaration adds final Word/PDF, supplement, cover-letter, table/figure and notice files with pinned render-input hashes and reuse-rights records. Copies preserve file bytes; content and visual fidelity stay not_assessed until separately reviewed. Build refuses edited or frozen outputs and destructive path collisions. Read bundle workflow for the schema, a runnable synthetic example and the limits of each recorded check.

Pre-flight gate (single command — last step before freeze)

Run this once, right before freeze/submission:

python "${CLAUDE_SKILL_DIR}/scripts/preflight_gate.py" --project-root . --journal chest
# add --strict to also halt on the heuristic/conditional (P1) checks
# add --online to make fabricated / author-mismatched references halt (PubMed/CrossRef)
# add --double-blind to make the asset-anonymization scan halt

It shells out to the per-check scripts (reimplementing none), writes qc/preflight_gate_report.json, and exits 0 clean, 1 halt (≥1 blocker), 2 gate config error (e.g. a --require'd check could not run). A non-zero exit blocks the freeze.

• P0 — halts by default (unambiguous, deterministic errors): leftover placeholder/markers (check_placeholders.py), undefined [@key] citations (check_citation_keys.py), duplicate references (verify_refs.py, offline-deterministic), a canonical-vs-submission hash mismatch (sync_submission.py audit), and an internal-audit dump in a reviewer-facing file (check_checklist_dump_leak.py).
• P1 — runs and reports warn, halts only with --strict or --require ID: check_xref, detect_copy_divergence, scope_drift_check, cover_letter_drift_check, cross_document_n_check, check_cross_artifact_stale; check_asset_anonymization is P1 unless --double-blind.
• A check whose inputs are absent (no rendered docx, no cover letter, no copies, no journal) is recorded skipped, never a blocker. A check that ran and failed — a traceback, an unexpected exit code, or a "missing input" exit while its inputs are present (malformed .journal_meta.json, an undecodable cover letter, a named --copy that does not exist, an unreadable file in the N scan) — is recorded error: submission_safe is false and the gate exits 2, with or without --strict.

Do not read the report as approval. Its legacy submission_safe field means only "no configured blocker/error"; readiness stays not_assessed; the optional bundle hash binding identifies the package present during the run, not per-file visual inspection or every external check input. Run audit again after preflight to expose current, stale or unbound evidence. Freeze records a byte snapshot and its available check context; it does not run preflight or approve source fidelity or reuse permissions.

Audit-dump leak check (P0). A /check-reporting or /self-review report is an internal working audit — auto-fix annotations, a raw JSON block (compliance_pct, fixable_by_ai, check_reporting_version), pipeline-log paths, "Action Items". It is not the official reporting checklist a journal expects and must never reach a reviewer, even when its filename looks official (e.g. STROBE_checklist_v4.pdf reused into a later package). scripts/check_checklist_dump_leak.py --dir submission/ scans every .md/.docx/.pdf in the package for these tokens; any hit is a P0 leak. The pre-flight runs it over the journal asset directory; confirm submission_safe: true before freeze. Writes qc/checklist_dump_leak.json.

Disclosure & availability check (standalone). Top medical-AI journals require, before review, an AI-use disclosure carrying four tokens (version + access channel + date/date-range + responsible party — the tool name only triggers the check) and Data/Code Availability statements. Run python3 ${CLAUDE_SKILL_DIR}/scripts/check_disclosure_availability.py --manuscript <file> --journal <stem> [--ai-study] [--require data_availability ...] [--strict] (reads references/journal_availability_policy.json). It blocks on a missing required statement or an AI disclosure that is present but missing a token / carrying a placeholder; "available on reasonable request" where the journal expects a repository is a P1 warning. Writes qc/disclosure_availability_report.json.

Workflow

1. Resolve canonical manuscript from project.yaml or explicit input.
2. Run the script in the requested mode.
3. If audit reports DRIFT, do not retarget or freeze until the user either patches the canonical manuscript or records the difference as journal-only. Never silently merge submission edits back into the SSOT, and never hide a journal-only difference — record it as drift or an explicit exception.
4. If build succeeds, run /verify-refs before final submission.
5. Call a package current only when its source hashes match, and mark it submitted only through freeze, which writes .journal_meta.json.

Quality Gates

• Gate 0 (pre-flight, last step before freeze): run scripts/preflight_gate.py as in "Pre-flight gate" above; non-zero exit blocks the freeze. It orchestrates Gates 1–3, 5b, 5c, 5d, 8, 9, 11, 11b, the Phase 3b/3c checks, and the placeholder and citation-key checks; each gate also runs on its own.

• Gate 1: block freezing when canonical manuscript is missing.

• Gate 2: block retargeting when the previous submission has unresolved drift.

• Gate 3: require /verify-refs audit before marking a package submission-safe. The pre-flight's offline references pass covers only duplicates and pagination placeholders; an online /verify-refs --strict against PubMed/CrossRef is the authoritative fabrication and author-name check.

• Gate 4 (recursive docx walk): every docx stale-string audit must walk paragraphs + tables + nested-table cells recursively. document.paragraphs skips table cells, document.tables does not recurse, and paragraph.runs hides runs inside <w:hyperlink> — and figures, captions and reporting checklists often sit in 1×1 or nested tables. For run-level edits near hyperlinks or fields, inspect the paragraph XML, not .runs: a hidden inline element can look like an empty () and be "fixed" into a real defect.

• Gate 5 (portal free-text fields): cover letter, data availability, acknowledgements, abstract and author contributions are often typed into the portal, outside any docx this skill audits. Before freeze, diff the portal's final review page against the manuscript body 1:1 and treat each field as its own drift target.

• Gate 5c (portal-field markdown residue): portal paste-verbatim .txt fields (abstract.txt, keywords.txt, …) are cut from the markdown but never stripped of it, so a trailing ---, a **bold**, or a cm^2^ superscript publishes literally. The pre-flight runs scripts/check_portal_field_residue.py --dir portal_fields/ (P1, --strict-promotable); only .txt is scanned (a .md is meant to carry markdown). Its Minor char_expansion advisory flags ≥/≤, which ScholarOne expands to "{greater than or equal to}" (five words), inflating the word count — pre-substitute >=/<= (only ≥/≤; × and the en-dash paste cleanly).

• Gate 5d (figure portal readiness): a figure bounces at the upload button for reasons decidable from the file on disk — byte size (JACC: Asia caps a figure at 25 MB) and extension (SNAPP accepts only .tiff/.jpeg/.eps, rejecting .png). The pre-flight runs scripts/figure_portal_readiness_check.py --figures-dir <dir> (P1) over submission/<journal>/figures (or ./figures), emitting FIGURE_OVERSIZE and — when the portal's formats are supplied, e.g. --figure-accept tiff --figure-accept jpeg --figure-accept eps — FIGURE_FORMAT_REJECTED. Fix by regenerating with /make-figures export_portal_tiff.py (LZW + RGBA→RGB flatten). No figures directory → skipped, never an error.

• Gate 6 (double-blind journals): a clean manuscript blind does not imply a clean portal blind. Before freeze, export the portal's blinded review PDF — the authoritative drift detector — and grep for all author identifiers across the entire upload set: manuscript; supplementary materials (especially methodology logs, agreement metrics, amendment logs); cover letter (a separately uploaded file is reviewer-visible unless toggled "Don't show in review PDF"); registry/approval PDFs (PROSPERO, ClinicalTrials.gov, IRB); portal Letter-field text if a signature was pasted; response-to-reviewers in revision rounds. Cover both period and no-period initials (G.S. and GS), full names in roman + native scripts, institution names, ORCID IDs and submission email domains.

• Gate 7 (text-only docx rebuilds): never use pandoc --reference-doc=manuscript.docx for response/cover/supplementary text-only docx, because the reference docx ships its embedded media (figure files) into the new docx, bloating it 50–100×. Use plain pandoc input.md -o output.docx. If such a file grows past 100 KB, unzip -l output.docx | grep word/media/ should come back empty.

• Gate 5b (cover-letter free-text drift): before freeze — see Phase 4.

• Gate 8 (cross-document N consistency): before freeze — see Phase 5.

• Gate 9 (intra-manuscript scope drift): see Phase 6.

• Gate 10 (v_(N+1) docx regeneration): when building from a frozen prior version — see Phase 7.

• Gate 11 (multi-copy divergence): before freeze or circulation — see Phase 8.

• Gate 11b (reframe / headline-change survivor scan): after a revision that reframes a claim class (e.g. retires "location-stratified benchmark" for "overall pooled") or changes a headline number, the old term/value often survives in an untouched paragraph, legend, the supplement or the response letter — even when the letter claims the change was applied "throughout". Pass the retired vocabulary and superseded values from the reframe diff to the cross-artifact gate, which scans the body and every aux artifact:

  python3 "${CLAUDE_SKILL_DIR}/scripts/check_cross_artifact_stale.py" \
      --manuscript manuscript.md --aux supplement/ --aux figures/legends.md --aux revision/response_to_reviewers.md \
      --retired-term "location-stratified benchmark" --old-value 1.72

  A retired_framing_survivor / stale_old_value finding is a P1 stale claim-site. --aux takes files or folders: .docx sidecars are read, and figure scripts (.py/.R) are swept for stale literals only. An --aux that holds no readable file exits 2 instead of passing, and unreadable documents (.pdf, .pptx, …) are listed as not checked. For any wording or number change, also grep the OLD string across the entire SSOT tree, never a subset, and watch for substring near-misses — an exact grep for expertise-dependent patterns passes while expertise-dependent evaluation patterns stays stale.

• Gate 12 (target-journal metadata drift): on build / retarget, compare the target the manuscript is written for — project.yaml target (and any in-manuscript header/footer "for submission to X" string) — against the journal the package is built for, and check the structural metadata the target dictates — abstract heading structure (4- vs 5-heading), body word limit, citation style (Vancouver / AMA), required elements (Highlights / Central Illustration / Key Points). A mismatch (e.g., a header still reading the previous journal after a cascade retarget, or a 4-heading abstract for a 5-heading target) is a target-restructure trigger — branch to v_(N+1) and sync every sidecar (cover letter, title page, ICMJE COI list) — not a silent build.

  # header target vs project.yaml target
  TGT=$(python3 -c "import yaml;print(yaml.safe_load(open('project.yaml')).get('target',''))" 2>/dev/null)
  grep -niE 'for submission to|submitted to|prepared for' manuscript/manuscript.md   # compare against "$TGT"

• Gate 13 (body word count vs journal cap — the revision-inflation trap): resolving reviewer majors adds words, so a revised body silently breaches the journal's limit. Before freeze and after every /revise pass, run scripts/check_wordcount_cap.py against the target journal profile's body cap. WORDCOUNT_OVER_CAP is a P0 (relocate methods/sensitivity detail to the Supplement); WORDCOUNT_NEAR_CAP (>0.95×) warns that the next pass will breach. The binding number is the rendered count (citeproc expands [@key] → "(Author Year)"), so prefer the built DOCX count with --rendered-words N; otherwise the script estimates it from the markdown body + inline-citation expansion.

  python3 "${CLAUDE_SKILL_DIR}/scripts/check_wordcount_cap.py" \
    --manuscript manuscript/manuscript.md \
    --journal-profile "${CLAUDE_SKILL_DIR}/../find-journal/references/journal_profiles/<Journal>.md" \
    --article-type "Original Article" --out qc/wordcount_cap.json --strict
  # or, deterministic: --limit <the journal's body cap>   (and --rendered-words N from the built DOCX when available)

  The profile cap is read only from a structured field: the body-limit column of an article-type table (| Type | Body Word Limit | Abstract | ... |), or, when no table carries the type, a list item that starts with it (- Original Article (4,000 words, ...)). Prose that merely mentions the type (often an abstract limit) is never read; when no single number results, or the cell holds more than one number, the script exits 2 and asks for --limit.

• Gate 14 (supplement structure — the numbering lock): a supplement of S{N}_*.md sections plus an index, hand-concatenated into _combined.md, desynchronizes across revision rounds — an index row with no file, a file the index never lists, two files claiming the same S{N}, a sub-section gap after an insert (S6.3 then S6.5) — and "Supplementary Table S9" opens the wrong content. Before freeze, run scripts/assemble_supplement.py to validate index↔file 1:1, rebuild _combined.md in index order (reproducible rather than hand-maintained), and — with --manuscript — report body callouts with no section file (CALLOUT_WITHOUT_SECTION) and section files the body never cites (SECTION_UNCITED). The four structural kinds are P0 under --strict; coverage findings are advisory.

  python3 "${CLAUDE_SKILL_DIR}/scripts/assemble_supplement.py" \
    --dir submission/{journal}/supplementary --index 00_index.md \
    --manuscript manuscript/manuscript.md \
    --out submission/{journal}/supplementary/_combined.md \
    --json qc/supplement_structure.json --strict