medsci-skills 4.1.0

package/skills/sync-submission/tests/test_copy_divergence.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Regression test for the multi-copy manuscript divergence detector (Phase 8).
+# Synthetic fixtures: an SSOT and two copies — one reworded but claim-complete
+# (OK), one missing an SSOT claim (p = 0.074, an unpropagated edit). Stdlib-only.
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/detect_copy_divergence.py"
+SSOT="$HERE/fixtures/ssot.md"
+OKC="$HERE/fixtures/copy_ok.md"
+STALE="$HERE/fixtures/copy_stale.md"
+OUT="$(mktemp -t cd_XXXX).json"
+trap 'rm -f "$OUT"' EXIT
+
+fail=0
+check() { local label="$1"; shift
+    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
+    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
+}
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+# OK copy alone -> exit 0.
+python3 "$SCRIPT" --ssot "$SSOT" --copy "$OKC" --strict >/dev/null 2>&1
+check "exit 0 when the copy carries every SSOT claim" test "$?" -eq 0
+
+# Stale copy -> exit 1, flags the unpropagated claim.
+python3 "$SCRIPT" --ssot "$SSOT" --copy "$OKC" --copy "$STALE" --out "$OUT" --strict >/dev/null 2>&1
+check "exit 1 when a copy is missing an SSOT claim" test "$?" -eq 1
+check "verdict DIVERGENT" python3 -c "
+import json; assert json.load(open('$OUT'))['verdict']=='DIVERGENT'"
+check "stale copy flags the unpropagated p-value" python3 -c "
+import json
+d=json.load(open('$OUT'))
+stale=[c for c in d['copies'] if c['verdict']=='STALE_COPY']
+assert stale and any('p=0.074' in u for u in stale[0]['unpropagated_to_copy'])"
+check "OK copy not flagged" python3 -c "
+import json
+d=json.load(open('$OUT'))
+ok=[c for c in d['copies'] if c['copy'].endswith('copy_ok.md')]
+assert ok and ok[0]['verdict']=='OK'"
+
+echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
+exit "$fail"

package/skills/sync-submission/tests/test_cross_artifact_stale.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Test scripts/check_cross_artifact_stale.py — the A3 cross-artifact staleness gate.
+# Synthetic, PII-free fixtures: a body that corrects two labeled values, a stale
+# supplement that disagrees, a checklist built against an older manuscript version,
+# and a clean supplement that agrees.
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/check_cross_artifact_stale.py"
+PASS=0
+FAIL=0
+ok()  { echo "  PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+# body (v8 in filename) — corrected values
+cat > "$WORK/manuscript_v8.md" <<'EOF'
+## Results
+The complete-case analysis included 95.7% of the cohort.
+Inter-rater agreement was substantial (kappa = 0.923).
+EOF
+
+# stale supplement: disagreeing values for the same labels
+mkdir -p "$WORK/aux"
+cat > "$WORK/aux/supplement.md" <<'EOF'
+Footnote: complete-case retention was 7.5% after exclusions.
+Reliability sub-analysis: kappa = 0.904.
+EOF
+
+# checklist built against an older manuscript version
+cat > "$WORK/aux/strobe_checklist.md" <<'EOF'
+Target manuscript: cohort study v6 (2026-04-20)
+Item 13: see Results, line 42.
+EOF
+
+# clean supplement that agrees with the body
+mkdir -p "$WORK/clean"
+cat > "$WORK/clean/supplement.md" <<'EOF'
+Footnote: complete-case retention was 95.7%.
+Reliability: kappa = 0.923.
+EOF
+
+run() { python3 "$SCRIPT" "$@" 2>/dev/null; }
+
+# 1. drift + version-stale -> exit 1
+run --manuscript "$WORK/manuscript_v8.md" --aux "$WORK/aux" --quiet
+[ $? -eq 1 ] && ok "stale aux + old checklist version -> exit 1" || bad "should fail"
+
+# 2. JSON reports both finding types
+run --manuscript "$WORK/manuscript_v8.md" --aux "$WORK/aux" --out "$WORK/r.json" --quiet
+python3 -c "
+import json,sys
+d=json.load(open('$WORK/r.json'))
+types={f['type'] for f in d['findings']}
+sys.exit(0 if {'labeled_value_drift','checklist_version_stale'} <= types
+         and d['summary']['stale'] >= 2 and d['summary']['version_stale'] >= 1 else 1)
+" && ok "JSON: labeled_value_drift (kappa+complete_case) + version_stale" || bad "JSON findings incomplete"
+
+# 3. explicit --manuscript-version overrides filename inference
+run --manuscript "$WORK/manuscript_v8.md" --aux "$WORK/aux/strobe_checklist.md" \
+    --manuscript-version v8 --out "$WORK/r2.json" --quiet
+python3 -c "
+import json,sys
+d=json.load(open('$WORK/r2.json'))
+sys.exit(0 if d['summary']['version_stale'] == 1 else 1)
+" && ok "explicit --manuscript-version flags stale checklist" || bad "version flag failed"
+
+# 4. clean supplement that agrees -> exit 0
+run --manuscript "$WORK/manuscript_v8.md" --aux "$WORK/clean" --quiet
+[ $? -eq 0 ] && ok "agreeing supplement passes" || bad "agreeing supplement should pass"
+
+# 5. missing --aux -> usage error (exit 2)
+run --manuscript "$WORK/manuscript_v8.md" --quiet
+[ $? -eq 2 ] && ok "missing --aux -> exit 2" || bad "missing --aux should be usage error"
+
+echo ""
+echo "test_cross_artifact_stale: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/skills/sync-submission/tests/test_cross_document_n.sh

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Regression tests for sync-submission cross_document_n_check.py.
+#
+# Synthetic fixtures only (no project paths, no manuscript IDs).
+# Skip with NETWORK=0 — this script does not use the network.
+#
+# Usage:
+#   skills/sync-submission/tests/test_cross_document_n.sh
+# Exit codes:
+#   0 — all tests passed
+#   1 — at least one test regressed
+#   2 — environment problem
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/skills/sync-submission/scripts/cross_document_n_check.py"
+TMP="$(mktemp -d -t cross_doc_n.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+if [[ ! -f "$SCRIPT" ]]; then
+    echo "ENV-ERR: script not found at $SCRIPT" >&2
+    exit 2
+fi
+command -v python3 >/dev/null 2>&1 || { echo "ENV-ERR: python3 missing" >&2; exit 2; }
+
+fail=0
+ran=0
+
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+# --------------------------------------------------------------------------
+# Case 1: two documents agreeing on N. Should PASS (exit 0).
+# --------------------------------------------------------------------------
+PROJ1="$TMP/case1_consistent"
+mkdir -p "$PROJ1"
+cat > "$PROJ1/abstract.md" <<'EOF'
+We included 42 studies after screening.
+EOF
+cat > "$PROJ1/manuscript.md" <<'EOF'
+Results section. Across 42 included studies, the pooled estimate was...
+EOF
+python3 "$SCRIPT" --root "$PROJ1" --out "$PROJ1/qc/n.json" --quiet
+assert_exit "case 1: consistent N (42 = 42)" 0 $?
+
+# --------------------------------------------------------------------------
+# Case 2: drift. Should FAIL (exit 1).
+# --------------------------------------------------------------------------
+PROJ2="$TMP/case2_drift"
+mkdir -p "$PROJ2"
+cat > "$PROJ2/abstract.md" <<'EOF'
+We included 63 studies after dual-reviewer screening.
+EOF
+cat > "$PROJ2/manuscript.md" <<'EOF'
+A total of 64 included studies were extracted for synthesis.
+EOF
+python3 "$SCRIPT" --root "$PROJ2" --out "$PROJ2/qc/n.json" --quiet
+assert_exit "case 2: drift (63 vs 64)" 1 $?
+# Verify the JSON content is well-formed and flags the right category.
+python3 - "$PROJ2/qc/n.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh:
+    rep = json.load(fh)
+assert rep["submission_safe"] is False, rep
+assert rep["drift_count"] == 1, rep
+assert rep["drifts"][0]["category"] == "included", rep
+vs = set(rep["drifts"][0]["values"])
+assert vs == {63, 64}, rep
+PY
+
+# --------------------------------------------------------------------------
+# Case 3: pool-lock mismatch.
+# --------------------------------------------------------------------------
+if python3 -c "import yaml" 2>/dev/null; then
+    PROJ3="$TMP/case3_lock"
+    mkdir -p "$PROJ3"
+    cat > "$PROJ3/abstract.md" <<'EOF'
+We included 50 studies after screening.
+EOF
+    cat > "$PROJ3/manuscript.md" <<'EOF'
+Across 50 included studies, the pooled estimate was ...
+EOF
+    cat > "$PROJ3/lock.yaml" <<'EOF'
+freeze_date: 2026-01-01
+final_pool_n: 48
+include_count: 48
+exclude_count: 100
+EOF
+    python3 "$SCRIPT" --root "$PROJ3" --pool-lock "$PROJ3/lock.yaml" \
+        --out "$PROJ3/qc/n.json" --quiet
+    assert_exit "case 3: pool-lock mismatch (50 vs locked 48)" 1 $?
+    python3 - "$PROJ3/qc/n.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh:
+    rep = json.load(fh)
+assert rep["lock_violations"], rep
+v = rep["lock_violations"][0]
+assert v["violation"] == "pool-lock-mismatch", v
+assert v["expected"] == 48, v
+assert v["actual"] == 50, v
+PY
+else
+    printf '  SKIP  %-50s reason=pyyaml unavailable\n' "case 3: pool-lock"
+fi
+
+# --------------------------------------------------------------------------
+# Case 4: explicit --files. Should also work.
+# --------------------------------------------------------------------------
+PROJ4="$TMP/case4_files"
+mkdir -p "$PROJ4/sub"
+cat > "$PROJ4/sub/a.md" <<'EOF'
+We included 30 patients in the analysis.
+EOF
+cat > "$PROJ4/sub/b.md" <<'EOF'
+30 patients were enrolled.
+EOF
+python3 "$SCRIPT" --files "$PROJ4/sub/a.md" "$PROJ4/sub/b.md" \
+    --out "$PROJ4/qc/n.json" --quiet
+assert_exit "case 4: explicit --files PASS (30 = 30)" 0 $?
+
+echo ""
+echo "ran=$ran fail=$fail"
+[[ $fail -eq 0 ]]

package/skills/sync-submission/tests/test_preflight_gate.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# Test scripts/preflight_gate.py — the A6 submission pre-flight orchestrator.
+# Builds synthetic, PII-free fixture projects in a temp dir and asserts the gate
+# halts on a deterministic blocker, passes a clean package, tolerates absent
+# inputs (skipped, not blocker), normalizes the inverted cover_letter exit code,
+# and honors --require / --skip. Stdlib-only; offline (no network).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/preflight_gate.py"
+PASS=0
+FAIL=0
+ok()  { echo "  PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+
+DIRTY="$WORK/dirty"
+CLEAN="$WORK/clean"
+mkdir -p "$DIRTY/manuscript" "$CLEAN/manuscript" "$CLEAN/submission/chest/manuscript"
+
+# dirty: an unresolved [@NEW:] placeholder + a TODO; bib does not define the marker
+cat > "$DIRTY/manuscript/manuscript.md" <<'EOF'
+# Introduction
+
+We follow prior work [@smith2020] and a competing-risk model [@NEW:competing-risk].
+
+## Methods
+
+Analysis used R. TODO: cite the package.
+
+## References
+EOF
+cat > "$DIRTY/refs.bib" <<'EOF'
+@article{smith2020, title={A real paper}, author={Smith, John}, journal={NEJM}, year={2020}, doi={10.1056/x}}
+EOF
+
+# clean: no markers, every cited key defined
+cat > "$CLEAN/manuscript/manuscript.md" <<'EOF'
+# Introduction
+
+We follow prior work [@smith2020] using a competing-risk model.
+
+## Methods
+
+Analysis used R version 4.3.
+
+## References
+EOF
+cat > "$CLEAN/refs.bib" <<'EOF'
+@article{smith2020, title={A real paper}, author={Smith, John}, journal={NEJM}, year={2020}, doi={10.1056/x}}
+EOF
+
+J() { python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print(d[sys.argv[2]] if sys.argv[2] in d else json.dumps(d))" "$@"; }
+STATUS() { python3 -c "import json,sys; d=json.load(open(sys.argv[1])); c=[x for x in d['checks'] if x['id']==sys.argv[2]][0]; print(c['status'])" "$@"; }
+
+# 1. dirty halts with exit 1
+python3 "$SCRIPT" --project-root "$DIRTY" --quiet
+[ $? -eq 1 ] && ok "dirty package halts (exit 1)" || bad "dirty package should halt"
+
+# 2. report: halt true, placeholders blocker, absent inputs skipped (tolerance)
+RPT="$DIRTY/qc/preflight_gate_report.json"
+[ "$(J "$RPT" halt)" = "True" ] && ok "report halt=true" || bad "report halt should be true"
+[ "$(STATUS "$RPT" placeholders)" = "blocker" ] && ok "placeholders is a blocker" || bad "placeholders should block"
+[ "$(STATUS "$RPT" cover_letter_drift)" = "skipped" ] && ok "cover_letter_drift skipped (no cover letter)" || bad "cover_letter_drift should skip"
+[ "$(STATUS "$RPT" copy_divergence)" = "skipped" ] && ok "copy_divergence skipped (no copies)" || bad "copy_divergence should skip"
+[ "$(STATUS "$RPT" sync_drift)" = "skipped" ] && ok "sync_drift skipped (no journal)" || bad "sync_drift should skip"
+
+# 3. references is a P1 warn (offline unverified), never a blocker by itself
+[ "$(STATUS "$RPT" references)" = "warn" ] && ok "references offline -> warn (non-halting)" || bad "references should warn offline"
+
+# 4. clean package passes (exit 0)
+python3 "$SCRIPT" --project-root "$CLEAN" --quiet
+[ $? -eq 0 ] && ok "clean package passes (exit 0)" || bad "clean package should pass"
+[ "$(J "$CLEAN/qc/preflight_gate_report.json" submission_safe)" = "True" ] && ok "clean report submission_safe=true" || bad "clean should be submission_safe"
+
+# 5. inverted cover-letter exit code normalized to warn (default), blocker under --require
+cat > "$CLEAN/submission/chest/cover_letter.md" <<'EOF'
+Dear Editor, the manuscript is approximately 8000 words with 99 references. Sincerely,
+EOF
+python3 "$SCRIPT" --project-root "$CLEAN" --journal chest --quiet
+[ $? -eq 0 ] && ok "cover-letter drift warns (P1, non-halting by default)" || bad "cover drift should not halt by default"
+RC="$CLEAN/qc/preflight_gate_report.json"
+python3 -c "
+import json,sys
+d=json.load(open('$RC')); c=[x for x in d['checks'] if x['id']=='cover_letter_drift'][0]
+sys.exit(0 if c['exit_code']==2 and c['status']=='warn' else 1)
+" && ok "cover_letter inverted exit 2 normalized to warn" || bad "cover_letter exit normalization wrong"
+
+python3 "$SCRIPT" --project-root "$CLEAN" --journal chest --require cover_letter_drift --quiet
+[ $? -eq 1 ] && ok "--require cover_letter_drift promotes to blocker (halt)" || bad "--require should halt on cover drift"
+
+# 6. --strict promotes all P1 to halting (cover drift now blocks)
+python3 "$SCRIPT" --project-root "$CLEAN" --journal chest --strict --quiet
+[ $? -eq 1 ] && ok "--strict promotes P1 cover drift to halt" || bad "--strict should halt on cover drift"
+
+# 7. --skip removes a check
+python3 "$SCRIPT" --project-root "$CLEAN" --journal chest --strict --skip cover_letter_drift --quiet
+[ $? -eq 0 ] && ok "--skip cover_letter_drift drops it (clean pass under --strict)" || bad "--skip should drop the check"
+
+# 8. --require on a check that cannot run -> gate error (exit 2)
+python3 "$SCRIPT" --project-root "$DIRTY" --require sync_drift --quiet
+[ $? -eq 2 ] && ok "--require sync_drift (no journal) -> gate error exit 2" || bad "required-but-unrunnable should exit 2"
+
+# 9. unknown check id -> exit 2
+python3 "$SCRIPT" --project-root "$CLEAN" --require nonsense --quiet 2>/dev/null
+[ $? -eq 2 ] && ok "unknown --require id -> exit 2" || bad "unknown id should exit 2"
+
+echo ""
+echo "test_preflight_gate: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/skills/sync-submission/tests/test_scope_drift.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+# Regression tests for sync-submission scope_drift_check.py.
+#
+# Synthetic fixtures only. No network needed.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/skills/sync-submission/scripts/scope_drift_check.py"
+TMP="$(mktemp -d -t scope_drift.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+command -v python3 >/dev/null 2>&1 || { echo "ENV-ERR: python3 missing" >&2; exit 2; }
+
+fail=0
+ran=0
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+# --------------------------------------------------------------------------
+# Case 1: well-formed manuscript. AUC appears in Methods, Results, Limitations.
+# --------------------------------------------------------------------------
+MS1="$TMP/case1.md"
+cat > "$MS1" <<'EOF'
+## **METHODS**
+We computed the area under the curve (AUC) on the held-out test set. The
+primary metric is AUC = 0.820.
+
+## **RESULTS**
+The pooled AUC was 0.820 (95% CI 0.78 to 0.86).
+
+## **DISCUSSION**
+
+### Limitations
+A sensitivity analysis on the primary AUC of 0.820 was not pre-specified.
+EOF
+python3 "$SCRIPT" --manuscript "$MS1" --out "$TMP/case1.json" --quiet
+assert_exit "case 1: consistent anchor (0.820 in all)" 0 $?
+
+# --------------------------------------------------------------------------
+# Case 2: AUC 0.869 appears only in Limitations. Should FAIL.
+# --------------------------------------------------------------------------
+MS2="$TMP/case2.md"
+cat > "$MS2" <<'EOF'
+## **METHODS**
+We computed AUC on the held-out test set.
+
+## **RESULTS**
+The pooled AUC was 0.820 (95% CI 0.78 to 0.86).
+
+## **DISCUSSION**
+
+### Limitations
+A leave-pair-out sensitivity analysis produced an envelope of AUC values:
+primary pool of 0.869 (95% CI 0.81 to 0.92), with neighborhood values
+0.851, 0.872, 0.881, and 0.890.
+EOF
+python3 "$SCRIPT" --manuscript "$MS2" --out "$TMP/case2.json" --quiet
+assert_exit "case 2: 0.869 limits-only anchor" 1 $?
+python3 - "$TMP/case2.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh: rep = json.load(fh)
+anchors = [a["anchor"] for a in rep["limitations_only_anchors"]]
+assert "0.869" in anchors, anchors
+PY
+
+# --------------------------------------------------------------------------
+# Case 3: PROSPERO commits to Freeman-Tukey but Methods does not.
+# --------------------------------------------------------------------------
+MS3="$TMP/case3.md"
+PR3="$TMP/case3_prospero.md"
+cat > "$MS3" <<'EOF'
+## **METHODS**
+Pooled estimates were computed in Python with descriptive statistics only.
+
+## **RESULTS**
+Pooled value 0.50.
+EOF
+cat > "$PR3" <<'EOF'
+# PROSPERO Record
+
+Synthesis: Freeman-Tukey transformation followed by random-effects pooling
+(DerSimonian-Laird estimator).
+EOF
+python3 "$SCRIPT" --manuscript "$MS3" --prospero "$PR3" --out "$TMP/case3.json" --quiet
+assert_exit "case 3: PROSPERO Freeman-Tukey, methods absent" 1 $?
+python3 - "$TMP/case3.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh: rep = json.load(fh)
+methods_listed = [s["method"] for s in rep["synthesis_method_drift"]]
+assert "Freeman-Tukey" in methods_listed, methods_listed
+PY
+
+# --------------------------------------------------------------------------
+# Case 4: no prospero supplied + clean manuscript = PASS.
+# --------------------------------------------------------------------------
+MS4="$TMP/case4.md"
+cat > "$MS4" <<'EOF'
+## **METHODS**
+AUC = 0.700 on the validation set.
+
+## **RESULTS**
+External AUC = 0.700 (95% CI 0.65 to 0.75).
+
+## **DISCUSSION**
+The external AUC of 0.700 demonstrates ...
+EOF
+python3 "$SCRIPT" --manuscript "$MS4" --out "$TMP/case4.json" --quiet
+assert_exit "case 4: clean, no prospero" 0 $?
+
+echo ""
+echo "ran=$ran fail=$fail"
+[[ $fail -eq 0 ]]

package/skills/sync-submission/tests/test_vN_docx_assertion.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Regression tests for verify_package_integrity.py --assert-vN-docx-changed.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/scripts/verify_package_integrity.py"
+TMP="$(mktemp -d -t vNdocx.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+fail=0
+ran=0
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+# Case 1: identical bytes => FAIL
+printf 'identical bytes\n' > "$TMP/vN.docx"
+cp "$TMP/vN.docx" "$TMP/vNplus1.docx"
+python3 "$SCRIPT" --assert-vN-docx-changed \
+    --vN-docx "$TMP/vN.docx" --new-docx "$TMP/vNplus1.docx" >/dev/null 2>&1
+assert_exit "case 1: identical bytes (FAIL)" 1 $?
+
+# Case 2: different bytes => PASS
+printf 'different bytes for v_(N+1)\n' > "$TMP/vNplus1.docx"
+python3 "$SCRIPT" --assert-vN-docx-changed \
+    --vN-docx "$TMP/vN.docx" --new-docx "$TMP/vNplus1.docx" >/dev/null 2>&1
+assert_exit "case 2: different bytes (PASS)" 0 $?
+
+# Case 3: missing v_N => exit 2
+python3 "$SCRIPT" --assert-vN-docx-changed \
+    --vN-docx "$TMP/nonexistent.docx" --new-docx "$TMP/vNplus1.docx" >/dev/null 2>&1
+assert_exit "case 3: missing v_N (exit 2)" 2 $?
+
+# Case 4: missing --new-docx arg => exit 2
+python3 "$SCRIPT" --assert-vN-docx-changed \
+    --vN-docx "$TMP/vN.docx" >/dev/null 2>&1
+assert_exit "case 4: missing --new-docx (exit 2)" 2 $?
+
+echo ""
+echo "ran=$ran fail=$fail"
+[[ $fail -eq 0 ]]