sync-submission

Files (87)

• SKILL.md
• build_synthetic_bundle.py · examples/
• bundle_workflow.md · references/
• journal_availability_policy.json · references/
• marked_manuscript.md · references/
• springer_em_packaging.md · references/
• _quote_match.py · scripts/
• _yaml_frontmatter.py · scripts/
• assemble_supplement.py · scripts/
• author_registry_example.yaml · scripts/
• blind_sweep.py · scripts/
• build_marked_manuscript.py · scripts/
• check_asset_anonymization.py · scripts/
• check_checklist_dump_leak.py · scripts/
• check_credit_integrity.py · scripts/
• check_cross_artifact_stale.py · scripts/
• check_disclosure_availability.py · scripts/
• check_marked_manuscript.py · scripts/
• check_portal_field_residue.py · scripts/
• abstract.txt · scripts/check_portal_field_residue_challenge/fixture/negative/
• keywords.txt · scripts/check_portal_field_residue_challenge/fixture/negative/
• abstract.txt · scripts/check_portal_field_residue_challenge/fixture/positive/
• take_home.txt · scripts/check_portal_field_residue_challenge/fixture/positive/
• problem.md · scripts/check_portal_field_residue_challenge/
• verify.sh · scripts/check_portal_field_residue_challenge/
• check_portal_mirror.py · scripts/
• check_wordcount_cap.py · scripts/
• cover_letter_drift_check.py · scripts/
• manuscript_bad.md · scripts/credit_integrity_challenge/fixture/
• manuscript_good.md · scripts/credit_integrity_challenge/fixture/
• verify.sh · scripts/credit_integrity_challenge/
• cross_document_n_check.py · scripts/
• detect_copy_divergence.py · scripts/
• problem.md · scripts/figure_portal_readiness_challenge/
• verify.sh · scripts/figure_portal_readiness_challenge/
• figure_portal_readiness_check.py · scripts/
• manuscript.md · scripts/portal_mirror_challenge/fixture/
• acknowledgements.txt · scripts/portal_mirror_challenge/fixture/portal_complete/
• author_contributions.txt · scripts/portal_mirror_challenge/fixture/portal_complete/
• competing_interests.txt · scripts/portal_mirror_challenge/fixture/portal_complete/
• data_availability.txt · scripts/portal_mirror_challenge/fixture/portal_complete/
• acknowledgements.txt · scripts/portal_mirror_challenge/fixture/portal_dropped/
• author_contributions.txt · scripts/portal_mirror_challenge/fixture/portal_dropped/
• data_availability.txt · scripts/portal_mirror_challenge/fixture/portal_dropped/
• acknowledgements.txt · scripts/portal_mirror_challenge/fixture/portal_reflowed/
• author_contributions.txt · scripts/portal_mirror_challenge/fixture/portal_reflowed/
• competing_interests.txt · scripts/portal_mirror_challenge/fixture/portal_reflowed/
• data_availability.txt · scripts/portal_mirror_challenge/fixture/portal_reflowed/
• verify.sh · scripts/portal_mirror_challenge/
• preflight_gate.py · scripts/
• scope_drift_check.py · scripts/
• sync_submission.py · scripts/
• verify_package_integrity.py · scripts/
• skill.yml
• copy_ok.md · tests/fixtures/
• copy_stale.md · tests/fixtures/
• ssot.md · tests/fixtures/
• 00_index.md · tests/fixtures/suppl_bad/
• S1_methods.md · tests/fixtures/suppl_bad/
• S2_a.md · tests/fixtures/suppl_bad/
• …and 27 more

SKILL.md (first lines)

# 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

```bash
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:

```bash
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

| Artifact | Path | Purpose |
|---|---|---|
| Submission metadata | `submission/{journal}/.journal_meta.json` | Source hash, status, canonical path |
| Sync audit | `qc/submission_sync_{journal}.json` | Drift result consumed by orchestrator |
| Manifest update | `artifact_manifest.json` | Submission package registry |
| Pre-flight gate | `qc/preflight_gate_report.json` | Aggregated halt-on-failure manifest (see "Pre-flight gate" below) |
| Supplement structure | `qc/supplement_structure.json` | Gate 14: index↔file 1:1, sub-section gaps, callout coverage |

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](references/bundle_workflow.md) 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:

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

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills