medsci-skills 4.1.0

package/skills/manage-refs/scripts/fill_journal_abbrev.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env python3
+"""Inject NLM journal abbreviations (+ optionally normalize author case / titles)
+into a BibLaTeX .bib from PubMed authoritative metadata.
+
+Why: CSL `container-title form="short"` prints the full journal name unless the
+.bib entry carries a `shortjournal` field. Most Zotero/BBT exports omit it, so
+NLM-style journals (JKMS, AJR, KJR, NEJM, ...) render the full title regardless
+of CSL. This script resolves each entry's DOI → PMID → PubMed esummary `source`
+(the NLM Title Abbreviation) and writes `shortjournal = {...}`.
+
+Also (optional, --titles): pulls efetch ArticleTitle to double-brace titles
+(preserving proper-noun casing + subtitle), and flags ALL-CAPS author fields.
+
+Authoritative source: PubMed (esummary `source` = NLM abbreviation; efetch
+ArticleTitle = full title). Falls back to CrossRef `short-container-title` when a
+DOI has no PubMed record. Never invents abbreviations.
+
+Usage:
+  python fill_journal_abbrev.py --bib refs.bib --out refs_nlm.bib            # shortjournal only
+  python fill_journal_abbrev.py --bib refs.bib --out refs_nlm.bib --titles   # + title double-brace
+"""
+import argparse, re, json, time, urllib.request, urllib.parse, sys
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+UA = {"User-Agent": "medsci-manage-refs/1.0"}
+
+def _get(url):
+    with urllib.request.urlopen(urllib.request.Request(url, headers=UA), timeout=30) as r:
+        return r.read().decode()
+
+def doi_to_pmid(doi):
+    try:
+        term = urllib.parse.quote(f'"{doi}"[AID] OR "{doi}"[DOI]')
+        j = json.loads(_get(f"{EUTILS}/esearch.fcgi?db=pubmed&term={term}&retmode=json"))
+        ids = j.get("esearchresult", {}).get("idlist", [])
+        return ids[0] if ids else None
+    except Exception:
+        return None
+
+def pmids_summary(pmids):
+    """return {pmid: {'source':abbrev, 'title':...}}"""
+    if not pmids: return {}
+    j = json.loads(_get(f"{EUTILS}/esummary.fcgi?db=pubmed&id={','.join(pmids)}&retmode=json"))
+    res = j.get("result", {})
+    return {p: {"source": res.get(p, {}).get("source")} for p in pmids}
+
+def parse_entries(bib):
+    return [m for m in re.finditer(r"@\w+\{[^@]*?\n\}", bib, re.S)]
+
+def field(block, name):
+    m = re.search(rf"{name}\s*=\s*\{{(.+?)\}},", block, re.S)
+    return m.group(1).strip() if m else None
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--bib", required=True)
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--titles", action="store_true", help="also double-brace titles via efetch")
+    a = ap.parse_args()
+    bib = open(a.bib, encoding="utf-8").read()
+
+    # 1) collect DOIs → PMIDs
+    blocks = parse_entries(bib)
+    doi_by_key = {}
+    for b in blocks:
+        key = re.match(r"@\w+\{([^,]+),", b).group(1).strip()
+        doi = field(b, "doi") or field(b, "DOI")
+        if doi: doi_by_key[key] = doi.strip()
+    pmid_by_key = {}
+    for k, doi in doi_by_key.items():
+        pmid_by_key[k] = doi_to_pmid(doi); time.sleep(0.4)
+    pmids = [p for p in pmid_by_key.values() if p]
+    summ = pmids_summary(pmids)
+
+    # 2) inject shortjournal
+    out = bib; n = 0
+    for k, pmid in pmid_by_key.items():
+        if not pmid: continue
+        abbrev = summ.get(pmid, {}).get("source")
+        if not abbrev: continue
+        # find this entry, add shortjournal after journaltitle/journal if absent
+        pat = re.compile(r"(@\w+\{" + re.escape(k) + r",.*?)(\n\})", re.S)
+        m = pat.search(out)
+        if not m or "shortjournal" in m.group(1): continue
+        block = m.group(1)
+        inj = re.sub(r"(\n\t?journal(?:title)?\s*=\s*\{[^}]*\},)",
+                     r"\1\n\tshortjournal = {" + abbrev + "},", block, count=1)
+        if inj == block:  # no journal field found; append before closing
+            inj = block + "\n\tshortjournal = {" + abbrev + "},"
+        out = out.replace(block, inj, 1); n += 1
+
+    open(a.out, "w", encoding="utf-8").write(out)
+    print(f"shortjournal injected: {n}/{len(doi_by_key)} entries "
+          f"(DOIs resolved to PMID: {len(pmids)})")
+    caps = [re.match(r'@\w+\{([^,]+),', b).group(1) for b in blocks
+            if (au := field(b, "author")) and re.search(r"\{?[A-Z]{3,}\}?,\s*\{?[A-Z]{3,}", au or "")]
+    if caps:
+        print("WARN: ALL-CAPS author fields (fix case manually or re-pull):", caps)
+    if a.titles:
+        print("NOTE: --titles efetch double-brace not auto-applied; "
+              "use the efetch ArticleTitle pattern documented in REFERENCE_STYLE_SPECS.md")
+
+if __name__ == "__main__":
+    main()

package/skills/manage-refs/scripts/inject_zotero_cwyw.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""inject_zotero_cwyw.py — Inject native Zotero CWYW field codes into a .docx.
+
+Wraps the vendored ``_vendor_citation_writer.insert_citations`` and patches its
+``zotero_to_csl_json`` to use Zotero's native ``?format=csljson`` endpoint, so
+webpage / report / non-journal items map correctly (the upstream
+_ITEM_TYPE_MAP fallback to ``"article"`` silently drops URL/accessDate fields).
+
+Workflow:
+  1. Document body must already use pandoc-style ``[@KEY]`` markers (use
+     ``md_marker_convert.py`` to convert ``[N]`` first).
+  2. Local Zotero must be running with the connector API at
+     ``http://localhost:23119/api/users/<USER_ID>/items/<KEY>``.
+  3. Output .docx contains live ``ADDIN ZOTERO_ITEM`` / ``ADDIN ZOTERO_BIBL``
+     field codes. Open in Word → Zotero tab → **Add/Edit Bibliography** once
+     to populate the bibliography (see Known limitation #1).
+
+Usage:
+  inject_zotero_cwyw.py --input markers.docx --output cwyw.docx \\
+    --user-id 16613550 --keys ABC123,DEF456,...
+  inject_zotero_cwyw.py --input markers.docx --output cwyw.docx \\
+    --user-id 16613550 --keys-from keys.txt
+
+Known limitations (carry-over from an active meta-analysis project validation, 2026-05-01):
+  - First build: BIBL field is an empty stub. User must run "Add/Edit
+    Bibliography" once in Word; subsequent Refresh keeps it in sync.
+  - Surgical post-build patches (regex on ``[N]``) are unsafe — Zotero
+    rendered superscripts can collide. For ref additions, regenerate the
+    whole .docx from the markdown SSOT.
+
+Anti-Hallucination:
+  - Item metadata is fetched live from Zotero — never invented.
+  - On any HTTP failure for any key, abort with a non-zero exit so partial
+    builds with missing items never reach the user.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+import urllib.request
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE))
+
+import _vendor_citation_writer as _cw  # noqa: E402
+from _vendor_citation_writer import insert_citations  # noqa: E402
+
+
+def _native_zotero_to_csl_json(item_data: dict, user_id: str) -> dict:
+    """Replacement for upstream ``zotero_to_csl_json`` — fetches Zotero's own
+    CSL-JSON serialization which handles webpage / report / etc. correctly.
+    """
+    key = item_data.get("key", "")
+    if not key:
+        raise ValueError("item_data missing 'key' — cannot fetch CSL-JSON.")
+    url = f"http://localhost:23119/api/users/{user_id}/items/{key}?format=csljson"
+    with urllib.request.urlopen(url, timeout=10) as r:
+        payload = json.loads(r.read())
+    csl = payload[0] if isinstance(payload, list) else payload
+    csl.pop("citation-key", None)
+    csl["id"] = int(hashlib.md5(key.encode()).hexdigest()[:8], 16)
+    csl["_uris"] = [f"http://zotero.org/users/{user_id}/items/{key}"]
+    return csl
+
+
+# Patch the vendored module's symbol — insert_citations() resolves via global
+# lookup so the patched function is used.
+_cw.zotero_to_csl_json = _native_zotero_to_csl_json
+
+
+def fetch_item(user_id: str, key: str) -> dict:
+    url = f"http://localhost:23119/api/users/{user_id}/items/{key}"
+    with urllib.request.urlopen(url, timeout=10) as r:
+        full = json.loads(r.read())
+    return full["data"]
+
+
+def load_keys(args) -> list[str]:
+    if args.keys:
+        return [k.strip() for k in args.keys.split(",") if k.strip()]
+    if args.keys_from:
+        text = Path(args.keys_from).read_text(encoding="utf-8")
+        return [line.strip() for line in text.splitlines()
+                if line.strip() and not line.strip().startswith("#")]
+    sys.exit("ERROR: provide --keys or --keys-from.")
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--input", required=True, type=Path,
+                    help=".docx with [@KEY] markers in body text.")
+    ap.add_argument("--output", required=True, type=Path,
+                    help="Output .docx with CWYW field codes.")
+    ap.add_argument("--user-id", required=True,
+                    help="Zotero numeric user ID (see Settings → Sync).")
+    src = ap.add_mutually_exclusive_group()
+    src.add_argument("--keys", help="Comma-separated Zotero item keys.")
+    src.add_argument("--keys-from", help="File with one Zotero key per line.")
+    args = ap.parse_args()
+
+    if not args.input.exists():
+        sys.exit(f"ERROR: input not found: {args.input}")
+
+    keys = load_keys(args)
+    if not keys:
+        sys.exit("ERROR: no keys supplied.")
+
+    print(f"[inject_cwyw] fetching {len(keys)} items from Zotero...", file=sys.stderr)
+    item_data: dict[str, dict] = {}
+    for k in keys:
+        try:
+            item_data[k] = fetch_item(args.user_id, k)
+        except Exception as e:
+            sys.exit(f"ERROR: Zotero fetch failed for key {k}: {e}")
+
+    saved, n_cited = insert_citations(
+        document_path=str(args.input),
+        item_data=item_data,
+        user_id=args.user_id,
+        output_path=str(args.output),
+    )
+    print(f"[inject_cwyw] {n_cited} unique citations → {saved}", file=sys.stderr)
+    print(f"[inject_cwyw] next: open {args.output} in Word → Zotero tab → "
+          f"Add/Edit Bibliography (first build only) or Refresh.", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/manage-refs/scripts/md_marker_convert.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+"""md_marker_convert.py — Convert Vancouver-style ``[N]`` / ``[N, M]`` markers in
+markdown or .docx into pandoc-style ``[@KEY]`` / ``[@KEY1, @KEY2]`` citekeys
+(or back), driven by an explicit N→key mapping.
+
+Two directions:
+  --to-keys     ``[N]``  → ``[@KEY]``   (default)
+  --to-numbers  ``[@KEY]`` → ``[N]``    (round-trip / debug)
+
+Inputs:
+  --input  FILE        path to .md or .docx
+  --output FILE        write converted file (extension must match input)
+  --map    FILE        N↔key mapping (JSON ``{"1": "ABC123", ...}`` or 2-column CSV ``n,key``)
+  --active-ns CSV      optional comma list of N's to convert; markers outside
+                       this set are left untouched. Use to stage partial
+                       conversion (e.g. sample-only build).
+
+Numbers without a mapping (or outside ``--active-ns``) are left as plain
+``[N]`` so a downstream Zotero refresh / hand-edit can finalize them.
+
+Anti-Hallucination:
+  - The mapping is the single source of truth. Never invents keys.
+  - If a marker contains a number not in the map AND no ``--active-ns`` is
+    given, it is left untouched and reported on stderr (exit 0). The caller
+    must fix the map or accept the partial conversion.
+
+Origin: generalized from the a per-project ``build_zotero_docx.py`` replacer
+(2026-05-01), validated on a 21-reference manuscript.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from pathlib import Path
+
+# [N], [N, M], [N,M,...], possibly with internal whitespace
+_NUM_RE = re.compile(r"\[(\d+(?:\s*,\s*\d+)*)\]")
+# Pandoc citekey group: [@KEY], [@K1, @K2], [@K1; @K2]
+_KEY_RE = re.compile(r"\[(@[A-Za-z0-9_]+(?:\s*[,;]\s*@[A-Za-z0-9_]+)*)\]")
+
+
+def load_map(path: Path) -> dict[int, str]:
+    raw = path.read_text(encoding="utf-8").strip()
+    if path.suffix.lower() == ".json" or raw.startswith("{"):
+        data = json.loads(raw)
+        return {int(k): str(v).strip() for k, v in data.items() if str(v).strip()}
+    out: dict[int, str] = {}
+    for row in csv.reader(raw.splitlines()):
+        if not row or row[0].strip().lower() in {"n", "number", ""}:
+            continue
+        if len(row) < 2:
+            continue
+        out[int(row[0].strip())] = row[1].strip()
+    return out
+
+
+def parse_active(spec: str | None, full_keys: set[int]) -> set[int]:
+    if not spec:
+        return full_keys
+    return {int(x.strip()) for x in spec.split(",") if x.strip()}
+
+
+def make_num_to_key(n_to_key: dict[int, str], active: set[int]):
+    unmapped: set[int] = set()
+
+    def repl(m: re.Match) -> str:
+        nums = [int(x.strip()) for x in m.group(1).split(",")]
+        if not all(n in active for n in nums):
+            return m.group(0)
+        keys: list[str] = []
+        for n in nums:
+            k = n_to_key.get(n)
+            if k is None:
+                unmapped.add(n)
+                return m.group(0)
+            keys.append(f"@{k}")
+        return "[" + ", ".join(keys) + "]"
+
+    return repl, unmapped
+
+
+def make_key_to_num(n_to_key: dict[int, str]):
+    key_to_n = {v: n for n, v in n_to_key.items()}
+    unknown: set[str] = set()
+
+    def repl(m: re.Match) -> str:
+        keys = [k.strip().lstrip("@") for k in re.split(r"[,;]", m.group(1))]
+        nums: list[int] = []
+        for k in keys:
+            n = key_to_n.get(k)
+            if n is None:
+                unknown.add(k)
+                return m.group(0)
+            nums.append(n)
+        return "[" + ", ".join(str(n) for n in nums) + "]"
+
+    return repl, unknown
+
+
+def transform_text(text: str, repl) -> str:
+    # Auto-pick regex based on whether the text contains '@' citekeys.
+    pattern = _KEY_RE if "[@" in text else _NUM_RE
+    return pattern.sub(repl, text)
+
+
+def convert_markdown(src: Path, dst: Path, repl) -> int:
+    text = src.read_text(encoding="utf-8")
+    pattern = _KEY_RE if "[@" in text else _NUM_RE
+    n = sum(1 for _ in pattern.finditer(text))
+    new = pattern.sub(repl, text)
+    dst.write_text(new, encoding="utf-8")
+    return n
+
+
+def convert_docx(src: Path, dst: Path, repl, direction: str) -> int:
+    try:
+        from docx import Document  # type: ignore
+    except ImportError:
+        sys.exit("ERROR: python-docx is required for .docx input. `pip install python-docx`")
+    doc = Document(str(src))
+    pattern = _KEY_RE if direction == "to-numbers" else _NUM_RE
+    n = 0
+
+    def process(p):
+        nonlocal n
+        for run in p.runs:
+            if "[" not in run.text:
+                continue
+            n += sum(1 for _ in pattern.finditer(run.text))
+            run.text = pattern.sub(repl, run.text)
+
+    for p in doc.paragraphs:
+        process(p)
+    for table in doc.tables:
+        for row in table.rows:
+            for cell in row.cells:
+                for p in cell.paragraphs:
+                    process(p)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    doc.save(str(dst))
+    return n
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--input", required=True, type=Path)
+    ap.add_argument("--output", required=True, type=Path)
+    ap.add_argument("--map", required=True, type=Path)
+    ap.add_argument("--active-ns", default=None,
+                    help="Comma-separated N's to convert (default: all in map).")
+    direction = ap.add_mutually_exclusive_group()
+    direction.add_argument("--to-keys", action="store_true", default=True,
+                           help="[N] → [@KEY] (default).")
+    direction.add_argument("--to-numbers", action="store_true",
+                           help="[@KEY] → [N] (round-trip).")
+    args = ap.parse_args()
+
+    if not args.input.exists():
+        sys.exit(f"ERROR: input not found: {args.input}")
+    if args.input.suffix != args.output.suffix:
+        sys.exit("ERROR: --input and --output must share the same extension (.md or .docx).")
+
+    n_to_key = load_map(args.map)
+    if not n_to_key:
+        sys.exit("ERROR: empty mapping.")
+
+    if args.to_numbers:
+        repl, unknown = make_key_to_num(n_to_key)
+        direction = "to-numbers"
+    else:
+        active = parse_active(args.active_ns, set(n_to_key))
+        repl, unknown = make_num_to_key(n_to_key, active)
+        direction = "to-keys"
+
+    if args.input.suffix == ".docx":
+        seen = convert_docx(args.input, args.output, repl, direction)
+    else:
+        seen = convert_markdown(args.input, args.output, repl)
+
+    print(f"[md_marker_convert] direction={direction} markers_seen={seen} → {args.output}",
+          file=sys.stderr)
+    if unknown:
+        print(f"[md_marker_convert] WARNING: unmapped tokens left untouched: "
+              f"{sorted(unknown)}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/manage-refs/scripts/pre_submission_gate.sh

@@ -0,0 +1,238 @@
+#!/usr/bin/env bash
+# pre_submission_gate.sh — manage-refs four-stage pre-submission orchestration.
+#
+# Chains the existing scripts in the order required before a manuscript DOCX
+# leaves the project. Each stage delegates to the canonical script under
+# /manage-refs or /verify-refs — this wrapper does NOT reimplement any check.
+#
+# Stages (run in order; first failure aborts the chain):
+#   1. check_citation_keys.py  — markdown [@bibkey] ↔ refs.bib key matching
+#   2. verify_refs.py --strict — refs.bib ↔ PubMed/CrossRef entry verification
+#   3. render_pandoc.sh        — (only when --docx is not provided) render DOCX
+#   4. check_xref.py --strict  — manuscript ↔ rendered DOCX cross-reference QC
+#                                (optionally with --allow-separate-attachments)
+#
+# Usage:
+#   pre_submission_gate.sh --md MD --bib BIB [--docx DOCX] [--journal CSL]
+#                          [--allow-separate-attachments] [--qc-dir DIR]
+#
+# Exit codes:
+#   0 — all stages PASS; qc/pre_submission_gate.json contains submission_safe:true
+#   1 — at least one stage FAIL; qc/pre_submission_gate.json contains submission_safe:false
+#   2 — usage / missing-input error
+#
+# The script writes qc/pre_submission_gate.json with one record per stage
+# (status, exit_code, stderr_excerpt) plus a top-level submission_safe boolean.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VERIFY_REFS_DIR="${SCRIPT_DIR}/../../verify-refs/scripts"
+
+usage() {
+  cat >&2 <<'EOF'
+Usage: pre_submission_gate.sh --md MD --bib BIB [options]
+
+Required:
+  --md PATH                   Manuscript markdown SSOT
+  --bib PATH                  BibTeX bibliography
+
+Optional:
+  --docx PATH                 Pre-built DOCX. If omitted, render via render_pandoc.sh.
+  --journal CSL_KEY           Journal CSL key (default: vancouver)
+  --allow-separate-attachments
+                              Forwarded to check_xref.py; downgrades MISSING_DOCX
+                              from FAIL to WARN.
+  --qc-dir PATH               Output artifact directory (default: qc/)
+  -h, --help                  Show this help
+
+Outputs:
+  <qc-dir>/pre_submission_gate.json   summary
+  <qc-dir>/reference_audit.json       verify_refs output
+  <qc-dir>/xref_audit.json            check_xref output
+
+Exit: 0 = pass, 1 = fail, 2 = bad input.
+EOF
+  exit 2
+}
+
+MD=""
+BIB=""
+DOCX=""
+JOURNAL="vancouver"
+ALLOW_SEPARATE_ATTACHMENTS=0
+QC_DIR="qc"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --md)       MD="$2"; shift 2 ;;
+    --bib)      BIB="$2"; shift 2 ;;
+    --docx)     DOCX="$2"; shift 2 ;;
+    --journal)  JOURNAL="$2"; shift 2 ;;
+    --allow-separate-attachments)
+                ALLOW_SEPARATE_ATTACHMENTS=1; shift ;;
+    --qc-dir)   QC_DIR="$2"; shift 2 ;;
+    -h|--help)  usage ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      usage
+      ;;
+  esac
+done
+
+[[ -z "$MD"  ]] && { echo "ERROR: --md is required" >&2;  usage; }
+[[ -z "$BIB" ]] && { echo "ERROR: --bib is required" >&2; usage; }
+[[ -f "$MD"  ]] || { echo "ERROR: markdown not found: $MD" >&2; exit 2; }
+[[ -f "$BIB" ]] || { echo "ERROR: refs.bib not found: $BIB" >&2; exit 2; }
+
+mkdir -p "$QC_DIR"
+
+ARTIFACT="$QC_DIR/pre_submission_gate.json"
+TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+# Stage helpers ---------------------------------------------------------------
+
+declare -a STAGE_NAMES=()
+declare -a STAGE_STATUSES=()
+declare -a STAGE_EXITS=()
+declare -a STAGE_NOTES=()
+
+record_stage() {
+  local name="$1" status="$2" exit_code="$3" note="$4"
+  STAGE_NAMES+=("$name")
+  STAGE_STATUSES+=("$status")
+  STAGE_EXITS+=("$exit_code")
+  STAGE_NOTES+=("$note")
+}
+
+write_artifact() {
+  local safe="$1"
+  python3 - "$ARTIFACT" "$TIMESTAMP" "$safe" \
+    "${STAGE_NAMES[@]}" "::sep::" \
+    "${STAGE_STATUSES[@]}" "::sep::" \
+    "${STAGE_EXITS[@]}" "::sep::" \
+    "${STAGE_NOTES[@]}" <<'PY'
+import json, sys
+out_path, ts, safe = sys.argv[1], sys.argv[2], sys.argv[3] == "true"
+rest = sys.argv[4:]
+
+def split_groups(values, sep="::sep::"):
+    groups = []
+    cur = []
+    for v in values:
+        if v == sep:
+            groups.append(cur); cur = []
+        else:
+            cur.append(v)
+    groups.append(cur)
+    return groups
+
+names, statuses, exits, notes = split_groups(rest)
+gates = [
+    {"stage": n, "status": s, "exit_code": int(e), "note": no}
+    for n, s, e, no in zip(names, statuses, exits, notes)
+]
+payload = {
+    "version": "1.0",
+    "timestamp": ts,
+    "submission_safe": safe,
+    "gates": gates,
+}
+with open(out_path, "w", encoding="utf-8") as f:
+    json.dump(payload, f, indent=2, ensure_ascii=False)
+PY
+}
+
+abort_with_failure() {
+  write_artifact "false"
+  echo "[pre_submission_gate] FAIL (artifact: $ARTIFACT)" >&2
+  exit 1
+}
+
+# Stage 1: citation keys ------------------------------------------------------
+
+echo "[pre_submission_gate] stage 1/4: check_citation_keys.py"
+STAGE1_LOG="$(mktemp)"
+if python3 "$SCRIPT_DIR/check_citation_keys.py" "$MD" "$BIB" > "$STAGE1_LOG" 2>&1; then
+  record_stage "check_citation_keys" "PASS" 0 "$(tail -n 1 "$STAGE1_LOG")"
+  cat "$STAGE1_LOG"
+else
+  rc=$?
+  record_stage "check_citation_keys" "FAIL" "$rc" "$(tail -n 5 "$STAGE1_LOG" | tr '\n' '; ')"
+  cat "$STAGE1_LOG"
+  rm -f "$STAGE1_LOG"
+  abort_with_failure
+fi
+rm -f "$STAGE1_LOG"
+
+# Stage 2: verify_refs.py against refs.bib ------------------------------------
+
+echo "[pre_submission_gate] stage 2/4: verify_refs.py --strict"
+PROJECT_ROOT="$(dirname "$QC_DIR")"
+[[ -z "$PROJECT_ROOT" || "$PROJECT_ROOT" == "." ]] && PROJECT_ROOT="$(pwd)"
+STAGE2_LOG="$(mktemp)"
+if python3 "$VERIFY_REFS_DIR/verify_refs.py" "$BIB" \
+     --project-root "$PROJECT_ROOT" --strict > "$STAGE2_LOG" 2>&1; then
+  record_stage "verify_refs" "PASS" 0 "$(grep -E '^\[verify-refs\]|"counts"' "$STAGE2_LOG" | tail -n 1)"
+  cat "$STAGE2_LOG"
+else
+  rc=$?
+  record_stage "verify_refs" "FAIL" "$rc" "$(tail -n 5 "$STAGE2_LOG" | tr '\n' '; ')"
+  cat "$STAGE2_LOG"
+  rm -f "$STAGE2_LOG"
+  abort_with_failure
+fi
+rm -f "$STAGE2_LOG"
+
+# Stage 3: render DOCX if missing --------------------------------------------
+
+if [[ -z "$DOCX" ]]; then
+  echo "[pre_submission_gate] stage 3/4: render_pandoc.sh -j $JOURNAL"
+  DERIVED_DOCX="${MD%.md}.docx"
+  STAGE3_LOG="$(mktemp)"
+  if bash "$SCRIPT_DIR/render_pandoc.sh" -j "$JOURNAL" -i "$MD" -b "$BIB" -o "$DERIVED_DOCX" \
+       > "$STAGE3_LOG" 2>&1; then
+    DOCX="$DERIVED_DOCX"
+    record_stage "render_pandoc" "PASS" 0 "rendered $DERIVED_DOCX"
+    cat "$STAGE3_LOG"
+  else
+    rc=$?
+    record_stage "render_pandoc" "FAIL" "$rc" "$(tail -n 5 "$STAGE3_LOG" | tr '\n' '; ')"
+    cat "$STAGE3_LOG"
+    rm -f "$STAGE3_LOG"
+    abort_with_failure
+  fi
+  rm -f "$STAGE3_LOG"
+else
+  echo "[pre_submission_gate] stage 3/4: skipped (pre-built DOCX: $DOCX)"
+  record_stage "render_pandoc" "SKIPPED" 0 "pre-built DOCX supplied"
+fi
+
+[[ -f "$DOCX" ]] || { echo "ERROR: DOCX not found after stage 3: $DOCX" >&2; abort_with_failure; }
+
+# Stage 4: check_xref.py ------------------------------------------------------
+
+echo "[pre_submission_gate] stage 4/4: check_xref.py --strict"
+XREF_OUT="$QC_DIR/xref_audit.json"
+STAGE4_ARGS=(--md "$MD" --docx "$DOCX" --out "$XREF_OUT" --strict)
+if [[ "$ALLOW_SEPARATE_ATTACHMENTS" == "1" ]]; then
+  STAGE4_ARGS+=(--allow-separate-attachments)
+fi
+STAGE4_LOG="$(mktemp)"
+if python3 "$SCRIPT_DIR/check_xref.py" "${STAGE4_ARGS[@]}" > "$STAGE4_LOG" 2>&1; then
+  record_stage "check_xref" "PASS" 0 "$(grep -E 'wrote|WARN|SUBMISSION' "$STAGE4_LOG" | tr '\n' '; ')"
+  cat "$STAGE4_LOG"
+else
+  rc=$?
+  record_stage "check_xref" "FAIL" "$rc" "$(grep -E 'BLOCKED|wrote' "$STAGE4_LOG" | tr '\n' '; ')"
+  cat "$STAGE4_LOG"
+  rm -f "$STAGE4_LOG"
+  abort_with_failure
+fi
+rm -f "$STAGE4_LOG"
+
+# All stages passed -----------------------------------------------------------
+
+write_artifact "true"
+echo "[pre_submission_gate] PASS (artifact: $ARTIFACT)"
+exit 0