From 58d8ddbb07cf8253f0164e49277727961f9a49e7 Mon Sep 17 00:00:00 2001
From: luoye-cpu <3412829159@qq.com>
Date: Sun, 8 Nov 2026 04:34:17 +0800
Subject: [PATCH 1/2] test(tools): pin user-facing CLI text against golden
 transcripts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The gap audit (issue #3214, rows C15-01..C15-13) found that the text a
user actually reads — the vmaf/vmafx help, --version output, the sidecar
usage blocks, and the option-error and geometry-error transcripts —
could change without any test noticing. The codegen unit tests shape
synthetic fixtures, dnn/test_cli.sh greps three flag strings, and the
error-path tests assert exit codes and single substrings; none guards
the bytes the built binary serves (ADR-3402).

- test_vmaf_cli_text_golden.sh: the vmaf --help transcript, the
  --version format on both binaries, the vmafx alias behaviour
  (byte-identical help modulo argv[0]; its own VMAFX precision=max
  version line), the --width/--precision/--model error transcripts, and
  the raw-yuv geometry refusals (exit 2, exact sizes in the message).
- test_vmaf_roi_vpl_usage.sh: the hand-written vmaf_roi and vmaf_vpl
  usage blocks; the vpl half skips (exit 77) outside Linux SYCL builds
  and is verified by the Ubuntu SYCL lanes.
- test_vmaf_per_shot.sh: pin per_shot_print_usage() on both its --help
  (stdout, exit 0) and no-args (stderr, exit 1) paths.

Goldens live under core/tools/test/golden/ with argv[0] normalised and
\r stripped on both sides (Windows CRT writes CRLF through a pipe); the
vpl golden embeds the current VMAF_DEFAULT_MODEL_VERSION value on
purpose — a default-model bump regenerates it. A text change is made by
consciously regenerating its golden in the same pull request, so the
review diff shows the exact user-visible change.

## Deliverables (ADR-0108)

- [ ] **Research digest**: no digest needed: the gap is the #3214 audit itself; the transcript pins execute its prescription.
- [ ] **Decision matrix**: no alternatives to weigh beyond ADR-3402's recorded ones (codegen idempotency only, heredoc goldens, argv[0]-pinning) — all rejected there with reasons.
- [ ] **AGENTS.md invariant note**: no rebase-sensitive invariants: self-contained new test files plus one meson.build registration carry no ordering a rebase could silently break.
- [x] **Reproducer / smoke-test command** — `meson test -C build test_vmaf_cli_text_golden test_vmaf_roi_vpl_usage test_vmaf_per_shot` (the golden halves verified against the MinGW build on Windows 11; the vpl half exercises on the Ubuntu SYCL lanes).
- [ ] **CHANGELOG fragment**: no changelog entry needed: test-only, no user-discoverable surface change.

Closes #3214 rows C15-01, C15-02, C15-03, C15-07, C15-09, C15-10,
C15-11, C15-12 and C15-13. C15-08 no longer applies on master:
test_vmaf_read_error_exit.sh already greps the user-facing stderr
strings ("problem while reading pictures", "ended before"). C15-04/05/06
stay open pending a validation-dependency decision (JSON Schema, XSD and
CSV-column validation would introduce dependencies the repo does not
carry), and the C15-17..25 rows need a Go toolchain this contribution
does not assume.

Signed-off-by: luoye-cpu <3412829159@qq.com>
---
 REUSE.toml                                    |   8 +
 core/tools/test/golden/vmaf_help.txt          | 189 +++++++++++++++
 core/tools/test/golden/vmaf_per_shot_help.txt |  18 ++
 core/tools/test/golden/vmaf_roi_help.txt      |  20 ++
 core/tools/test/golden/vmaf_vpl_help.txt      |  13 ++
 core/tools/test/meson.build                   |  42 ++++
 core/tools/test/test_vmaf_cli_text_golden.sh  | 218 ++++++++++++++++++
 core/tools/test/test_vmaf_per_shot.sh         |  36 +++
 core/tools/test/test_vmaf_roi_vpl_usage.sh    |  92 ++++++++
 docs/adr/3402-cli-text-golden-pins.md         |  90 ++++++++
 .../3402-cli-text-golden-pins.md              |   1 +
 11 files changed, 727 insertions(+)
 create mode 100644 core/tools/test/golden/vmaf_help.txt
 create mode 100644 core/tools/test/golden/vmaf_per_shot_help.txt
 create mode 100644 core/tools/test/golden/vmaf_roi_help.txt
 create mode 100644 core/tools/test/golden/vmaf_vpl_help.txt
 create mode 100644 core/tools/test/test_vmaf_cli_text_golden.sh
 create mode 100644 core/tools/test/test_vmaf_roi_vpl_usage.sh
 create mode 100644 docs/adr/3402-cli-text-golden-pins.md
 create mode 100644 docs/adr/_index_fragments/3402-cli-text-golden-pins.md

diff --git a/REUSE.toml b/REUSE.toml
index c2463a40ac..26464b42da 100644
--- a/REUSE.toml
+++ b/REUSE.toml
@@ -9,6 +9,14 @@ precedence = "closest"
 SPDX-FileCopyrightText = "2026 Lusoris"
 SPDX-License-Identifier = "EUPL-1.2"
 
+# The CLI golden transcripts (ADR-3402) are diff targets: no inline SPDX
+# header may precede the pinned bytes, so their terms are annotated here
+# (ADR-3401: outside contributors name themselves as holders).
+[[annotations]]
+path = ["core/tools/test/golden/*.txt"]
+precedence = "override"
+SPDX-FileCopyrightText = "2026 luoye-cpu"
+SPDX-License-Identifier = "EUPL-1.2"
 # These six files descend from Netflix/vmaf root files.  ADR-1250 requires
 # inherited work, and every fork contribution to it, to remain on the terms it
 # already carried rather than being swept into the fork-local EUPL default.
diff --git a/core/tools/test/golden/vmaf_help.txt b/core/tools/test/golden/vmaf_help.txt
new file mode 100644
index 0000000000..93599e6a07
--- /dev/null
+++ b/core/tools/test/golden/vmaf_help.txt
@@ -0,0 +1,189 @@
+Usage: <app> [options]
+
+Supported options:
+ --reference/-r $path:         Reference video: a .y4m file, or raw planar .yuv
+                               together with the width, height, pixel format and
+                               bit depth.
+ --distorted/-d $path:         Distorted video, in the same form as the
+                               reference.
+ --width/-w $unsigned:         Width of raw .yuv input in pixels.
+ --height/-h $unsigned:        Height of raw .yuv input in pixels.
+ --width_ref $unsigned:        Width of the raw .yuv reference in pixels, if it
+                               differs from --width. Only models that scale
+                               their inputs accept different sizes.
+ --width_dist $unsigned:       Width of the raw .yuv distorted video in pixels,
+                               if it differs from --width. Only models that
+                               scale their inputs accept different sizes.
+ --height_ref $unsigned:       Height of the raw .yuv reference in pixels, if it
+                               differs from --height. Only models that scale
+                               their inputs accept different sizes.
+ --height_dist $unsigned:      Height of the raw .yuv distorted video in pixels,
+                               if it differs from --height. Only models that
+                               scale their inputs accept different sizes.
+ --pixel_format/-p $string:    Layout of raw .yuv input: 400 (luma only), 420,
+                               422 or 444 planar, or a layout of the input
+                               format table (semi-planar, packed, or RGB
+                               converted to Y'CbCr with the rgb_* statement,
+                               ADR-2145, ADR-2146). One of:
+                               400|420|422|444|nv12|nv16|nv24|p010|p016|p210|p216|p410|p416|yuyv422|uyvy422|v210|y210|y212|xv30|xv36|vuyx|ayuv|yuv444p16msb|rgb|rgba|bgra.
+ --bitdepth/-b $unsigned:      Bits per sample of raw .yuv input, 8 to 16
+                               (implied by a layout that fixes it).
+ --check-sample-range, --check_sample_range:
+                               Refuse a frame with a sample above 2^bpc - 1 and
+                               name the plane, row, column and value (ADR-1918).
+ --color_range_ref $string:    Colour range of the reference input. One of:
+                               unknown|limited|full.
+ --color_range_dist $string:   Colour range of the distorted input. One of:
+                               unknown|limited|full.
+ --color_primaries_ref $string:
+                               Colour primaries of the reference input. One of:
+                               unknown|bt709|bt2020.
+ --color_primaries_dist $string:
+                               Colour primaries of the distorted input. One of:
+                               unknown|bt709|bt2020.
+ --color_trc_ref $string:      Transfer characteristic of the reference input.
+                               One of: unknown|bt709|smpte2084|pq.
+ --color_trc_dist $string:     Transfer characteristic of the distorted input.
+                               One of: unknown|bt709|smpte2084|pq.
+ --color_matrix_ref $string:   Matrix coefficients of the reference input. One
+                               of: unknown|bt709|bt2020nc|ictcp.
+ --color_matrix_dist $string:  Matrix coefficients of the distorted input. One
+                               of: unknown|bt709|bt2020nc|ictcp.
+ --rgb_matrix $string:         Raw rgb, rgba and bgra input: the Y'CbCr matrix
+                               of the conversion; no default, the input is
+                               refused without it (ADR-2146). One of:
+                               bt601|bt709|bt2020ncl.
+ --rgb_range $string:          Raw RGB input: the range of the R'G'B' samples;
+                               no default. One of: limited|full.
+ --rgb_transfer $string:       Raw RGB input: the transfer characteristic of the
+                               R'G'B' samples (checked, not applied); no
+                               default. One of: bt709|srgb|pq|hlg.
+ --rgb_out_range $string:      Raw RGB input: the range of the Y'CbCr frame
+                               made; limited is the range the VMAF models are
+                               trained on; no default. One of: limited|full.
+ --model/-m $params:           Model, colon-delimited: version= a built-in
+                               model, path= a model file, name= the name in the
+                               report, disable_clip, enable_transform,
+                               <feature>.<option>=<value> overloads. Several
+                               models score in one pass (repeat the option; the
+                               filter separates them with |). (default:
+                               VMAF_DEFAULT_MODEL_VERSION)
+ --backend $name:              Backend: auto uses the available ones; any other
+                               value runs that backend alone and fails when it
+                               is not available. One of:
+                               auto|cpu|cuda|sycl|hip|metal. (default: auto)
+ --no_cuda:                    Disable the CUDA backend.
+ --no_sycl:                    Disable the SYCL (oneAPI) backend.
+ --no_hip:                     Disable the HIP (ROCm) backend.
+ --no_metal:                   Disable the Metal (Apple silicon) backend.
+ --feature $string:            Additional feature extractor,
+                               name[=key=value:...] (for example psnr or
+                               cambi=full_ref=true); several may be given (the
+                               filter separates them with |). Mutually exclusive
+                               with the CTC presets.
+ --aom_ctc $version:           AOM common test conditions preset: a fixed model
+                               and feature set. One of:
+                               v1.0|v2.0|v3.0|v4.0|v5.0|v6.0|v7.0.
+ --nflx_ctc $version:          Netflix common test conditions preset: a fixed
+                               model and feature set. One of: v1.0.
+ --tiny-model, --tiny_model $path:
+                               Tiny ONNX model to load alongside the classic
+                               models.
+ --tiny-device, --tiny_device $string:
+                               ONNX Runtime execution provider of the tiny
+                               model. One of:
+                               auto|cpu|cuda|openvino|openvino-npu|openvino-cpu|openvino-gpu|coreml|coreml-ane|coreml-gpu|coreml-cpu|rocm.
+                               (default: auto)
+ --dnn-ep, --dnn_ep $string:   Alias of the tiny-model device under the ONNX
+                               Runtime name (execution provider); both set the
+                               same setting. One of:
+                               auto|cpu|cuda|openvino|openvino-npu|openvino-cpu|openvino-gpu|coreml|coreml-ane|coreml-gpu|coreml-cpu|rocm.
+ --tiny-threads, --tiny_threads $unsigned:
+                               Intra-op threads of the CPU execution provider
+                               (0: the runtime's default).
+ --tiny-fp16, --tiny_fp16:     Request fp16 input and output where the execution
+                               provider supports it.
+ --tiny-model-verify, --tiny_model_verify:
+                               Require a Sigstore bundle verification of the
+                               tiny model (cosign verify-blob) before it loads;
+                               a missing bundle, a missing cosign or a failed
+                               verification refuses the model.
+ --tiny-codec, --tiny_codec $name:
+                               Encoder of the distorted clip, required by
+                               codec-aware tiny models (fr_regressor_v2/v3),
+                               which refuse to score without it. Must be in the
+                               model sidecar's encoder_vocab; the ffprobe names
+                               h264, hevc, av1, vp9 and vvc are accepted.
+ --tiny-preset, --tiny_preset $string:
+                               Encoder preset (medium, slow, p4, 5, ...), read
+                               as the encoder defines it. Unset: ordinal 5
+                               (medium). A model trained with one preset
+                               (fr_regressor_v3) ignores it and warns.
+ --tiny-crf, --tiny_crf $unsigned:
+                               CRF or QP used for the encode, normalised as the
+                               model sidecar declares. Required with the codec
+                               and preset.
+ --tiny-resize, --tiny_resize $string:
+                               Resize filter for NCHW tiny models whose input
+                               size differs from the frame; disabled refuses the
+                               mismatch (-ERANGE). The three filters give scores
+                               about 2% apart: record the filter with the model.
+                               One of: bilinear|nearest|bicubic|disabled.
+                               (default: disabled)
+ --no-reference, --no_reference:
+                               No-reference mode; needs a no-reference tiny
+                               model. The reference becomes a formality: only
+                               the distorted picture is scored.
+ --threads $unsigned:          Worker threads of the feature extractors, capped
+                               to the hardware threads (0: score in the calling
+                               thread).
+ --frame_cnt $unsigned:        Score at most this many frames.
+ --frame_skip_ref $unsigned:   Skip this many frames at the start of the
+                               reference.
+ --frame_skip_dist $unsigned:  Skip this many frames at the start of the
+                               distorted video.
+ --no_prediction/-n:           Extract features only; no model score.
+ --cpumask/-c $bitmask:        Bitmask of CPU instruction sets the extractors
+                               must not use.
+ --gpumask $bitmask:           Bitmask of GPU operations the extractors must not
+                               use.
+ --sycl_device $unsigned:      SYCL GPU by index (unset: selected
+                               automatically).
+ --hip_device $unsigned:       HIP GPU by index (opt-in: HIP is off unless this
+                               or --backend hip is given).
+ --metal_device $unsigned:     Metal GPU by index (opt-in: Metal is off unless
+                               this or --backend metal is given).
+ --subsample $unsigned:        Score every n-th frame (1: every frame).
+                               (default: 1)
+ --precision $spec:            Score precision: N (1 to 17) writes %.<N>g; max
+                               or full write %.17g (round-trip lossless); legacy
+                               writes %.6f (Netflix-compatible). The scoring
+                               server returns lossless scores unless asked
+                               otherwise. One of:
+                               legacy|max|full|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16|17.
+                               (default: legacy)
+ --output/-o $path:            Report file.
+ --xml:                        Report format; json and xml carry the backend
+                               receipt. xml (default)
+ --json:                       Report format; json and xml carry the backend
+                               receipt. json
+ --csv:                        Report format; json and xml carry the backend
+                               receipt. csv
+ --sub:                        Report format; json and xml carry the backend
+                               receipt. sub
+ --provenance-sidecar:         Also write the provenance record to
+                               <output>.provenance.json; CSV and SUB reports
+                               carry it nowhere else (RC4 WP5).
+ --netflix-compat, --netflix_compat:
+                               Restore the Netflix-upstream defaults: CPU
+                               backend, %.6f precision, vmaf_v0.6.1 model.
+ --quiet/-q:                   Disable the FPS meter when run in a terminal.
+ --version/-v:                 Print the version and exit.
+ --list-backends:              Print the scoring backends this binary was built
+                               with and which of them initialise here, as JSON,
+                               and exit (ADR-1874).
+ --help:                       Print this message and exit.
+ --verify-provenance $report:  Re-run the configuration a JSON report records
+                               and compare every configuration field and score
+                               bit for bit; exits nonzero naming the first
+                               difference (RC4 WP5).
diff --git a/core/tools/test/golden/vmaf_per_shot_help.txt b/core/tools/test/golden/vmaf_per_shot_help.txt
new file mode 100644
index 0000000000..94f1109e2c
--- /dev/null
+++ b/core/tools/test/golden/vmaf_per_shot_help.txt
@@ -0,0 +1,18 @@
+Usage: vmaf-perShot --reference REF.yuv --width W --height H --pixel_format 420|422|444 --bitdepth 8 --output PLAN [options]
+
+Required:
+  -r, --reference PATH       reference YUV file
+  -w, --width    N           frame width in pixels
+  -h, --height   N           frame height in pixels
+  -p, --pixel_format 420|422|444  planar YUV subsampling
+  -b, --bitdepth 8|10|12|16  planar YUV bit depth
+  -o, --output   PATH        per-shot plan output
+
+Optional:
+  -t, --target-vmaf X        target VMAF score [default 90]
+  -m, --crf-min N            minimum CRF clamp [default 18]
+  -M, --crf-max N            maximum CRF clamp [default 35]
+  -d, --diff-threshold X     shot-detector frame-diff cutoff
+  -f, --format csv|json      output format [default csv]
+  -F, --frames   N           maximum frames to scan (0 = all) [default 0]
+  -H, --help                 print this message
diff --git a/core/tools/test/golden/vmaf_roi_help.txt b/core/tools/test/golden/vmaf_roi_help.txt
new file mode 100644
index 0000000000..3498cc7300
--- /dev/null
+++ b/core/tools/test/golden/vmaf_roi_help.txt
@@ -0,0 +1,20 @@
+usage: vmaf-roi --reference REF.yuv --width W --height H \
+                --frame N --output qpfile [options]
+
+Required:
+  --reference PATH         Raw planar YUV input.
+  --width W                Frame width in luma samples.
+  --height H               Frame height in luma samples.
+  --frame N                0-based frame index to score.
+  --output PATH            Sidecar file (use '-' for stdout).
+
+Optional:
+  --pixel_format 420|422|444   Default 420.
+  --bitdepth 8|10|12|16        Default 8.
+  --ctu-size N                 8..128, default 64 (x265 max-ctu).
+  --encoder x265|svt-av1       Default x265.
+  --strength F                 QP-offset gain, default 6.0.
+  --saliency-model PATH        Optional ONNX [1,1,H,W] luma->[0,1].
+                               If absent, a center-weighted radial
+                               placeholder is used (smoke-test only).
+  -h, --help                   Show this help.
diff --git a/core/tools/test/golden/vmaf_vpl_help.txt b/core/tools/test/golden/vmaf_vpl_help.txt
new file mode 100644
index 0000000000..acc869b6ba
--- /dev/null
+++ b/core/tools/test/golden/vmaf_vpl_help.txt
@@ -0,0 +1,13 @@
+Usage: <app> --ref <file> --dis <file> [options]
+
+Options:
+  --ref <file>        Reference video file
+  --dis <file>        Distorted video file
+  --model <name>      VMAF model name (default: vmaf_v1.0.16_3d0h)
+  --frames <N>        Max frames to process (0 = all)
+  --device <N>        SYCL device index (default: 0)
+  --render-node <path> VA-API render node (default: /dev/dri/renderD128)
+  --fallback          Use host upload if zero-copy import fails
+  --help              Show this help
+
+Pipeline: VPL decode → VA surface → DMA-BUF → Level Zero → SYCL → VMAF
diff --git a/core/tools/test/meson.build b/core/tools/test/meson.build
index ae69daffef..290df06133 100644
--- a/core/tools/test/meson.build
+++ b/core/tools/test/meson.build
@@ -317,3 +317,45 @@ test('test_vmaf_raw_layouts', test_vmaf_raw_layouts,
          'MESON_BUILD_ROOT=' + meson.project_build_root(),
          'MESON_SOURCE_ROOT=' + meson.project_source_root(),
      ])
+
+# ADR-3402 — the user-facing text of the vmaf CLI is a contract: help, the
+# --version format, option-error transcripts and the yuv geometry refusals
+# are diffed against golden transcripts served by the real binary
+# (issue #3214 rows C15-01..C15-10). The vmafx alias is asserted to serve
+# byte-identical help and its own VMAFX version line.
+test_vmaf_cli_text_golden = find_program('test_vmaf_cli_text_golden.sh')
+test('test_vmaf_cli_text_golden', test_vmaf_cli_text_golden,
+     suite : ['fast'],
+     depends : [vmaf, vmafx],
+     workdir : meson.project_build_root(),
+     env: [
+         'MESON_BUILD_ROOT=' + meson.project_build_root(),
+         'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+     ],
+     timeout : 120)
+
+# ADR-3402 — the hand-written usage text of the vmaf_roi / vmaf_vpl sidecars
+# is pinned the same way (issue #3214 rows C15-12/C15-13); the vpl half
+# skips (exit 77) outside Linux SYCL builds, where its golden is verified.
+test_vmaf_roi_vpl_usage = find_program('test_vmaf_roi_vpl_usage.sh')
+if vmaf_vpl_ok
+    test('test_vmaf_roi_vpl_usage', test_vmaf_roi_vpl_usage,
+         suite : ['fast'],
+         depends : [vmaf_roi, vmaf_vpl],
+         workdir : meson.project_build_root(),
+         env: [
+             'MESON_BUILD_ROOT=' + meson.project_build_root(),
+             'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+         ],
+         timeout : 120)
+else
+    test('test_vmaf_roi_vpl_usage', test_vmaf_roi_vpl_usage,
+         suite : ['fast'],
+         depends : [vmaf_roi],
+         workdir : meson.project_build_root(),
+         env: [
+             'MESON_BUILD_ROOT=' + meson.project_build_root(),
+             'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+         ],
+         timeout : 120)
+endif
diff --git a/core/tools/test/test_vmaf_cli_text_golden.sh b/core/tools/test/test_vmaf_cli_text_golden.sh
new file mode 100644
index 0000000000..592d7b01fc
--- /dev/null
+++ b/core/tools/test/test_vmaf_cli_text_golden.sh
@@ -0,0 +1,218 @@
+#!/bin/sh
+# Copyright 2026 luoye-cpu
+# SPDX-License-Identifier: EUPL-1.2
+
+# test_vmaf_cli_text_golden.sh — pin the user-facing text of the `vmaf` CLI
+# (issue #3214 rows C15-01, C15-02, C15-03, C15-07, C15-09, C15-10; ADR-3402).
+#
+# Help text, version format, option-error transcripts and the yuv geometry
+# refusals are what a user actually reads; before this test any of them could
+# change silently (the codegen unit tests cover emitter shaping on synthetic
+# fixtures, not what the built binary serves, and dnn/test_cli.sh greps only
+# three flag strings). Every case here diffs the real binary's output against
+# the transcripts under test/golden/ — a text change fails here until the
+# golden is consciously regenerated.
+#
+# Portability: the first "Usage: ..." line embeds argv[0], which differs
+# across platforms and invocation paths, so it is normalised to
+# "Usage: <app> [options]" on both the golden and the captured output; the
+# same for the argv[0] prefix of the --precision refusal. Error transcripts
+# are "<reason>", an empty line, then the full usage dump, so the usage head
+# sits on line 3 there. Windows writes CRLF through a pipe (CRT text mode),
+# so \r is stripped on both sides too.
+set -eu
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+GOLDEN="$SCRIPT_DIR/golden/vmaf_help.txt"
+BIN=./tools/vmaf
+ALIAS=./tools/vmafx
+WORK="${MESON_BUILD_ROOT:-.}/test_vmaf_cli_text_golden.scratch"
+mkdir -p "${WORK}"
+
+fail() {
+  echo "test_vmaf_cli_text_golden: $1" >&2
+  exit 1
+}
+
+# Strip CR and blank the argv[0] of a "Usage: ... [options]" first line
+# (help/alias stdout).
+norm_help() {
+  sed -e 's/\r$//' \
+      -e '1s/^Usage: .* \[options\]$/Usage: <app> [options]/' "$1"
+}
+
+# Error transcripts: keep the reason line, blank the argv[0] of the usage
+# head on line 3.
+norm_err() {
+  sed -e 's/\r$//' \
+      -e '3s/^Usage: .* \[options\]$/Usage: <app> [options]/' "$1"
+}
+
+# --help must print the golden transcript on stdout, exit 0, and write
+# nothing to stderr. (C15-01)
+"$BIN" --help >"${WORK}/help.out" 2>"${WORK}/help.err" ||
+  fail "vmaf --help exited non-zero"
+if [ -s "${WORK}/help.err" ]; then
+  fail "vmaf --help wrote to stderr"
+fi
+sed -e 's/\r$//' "$GOLDEN" >"${WORK}/golden.norm"
+norm_help "${WORK}/help.out" >"${WORK}/help.norm"
+if ! diff -u "${WORK}/golden.norm" "${WORK}/help.norm" >"${WORK}/help.diff"; then
+  head -30 "${WORK}/help.diff" >&2
+  fail "vmaf --help drifted from the golden transcript"
+fi
+
+# The vmafx alias serves byte-identical help (modulo argv[0]). (C15-02)
+"$ALIAS" --help >"${WORK}/alias.out" 2>"${WORK}/alias.err" ||
+  fail "vmafx --help exited non-zero"
+if [ -s "${WORK}/alias.err" ]; then
+  fail "vmafx --help wrote to stderr"
+fi
+norm_help "${WORK}/alias.out" >"${WORK}/alias.norm"
+if ! diff -u "${WORK}/golden.norm" "${WORK}/alias.norm" >"${WORK}/alias.diff"; then
+  head -30 "${WORK}/alias.diff" >&2
+  fail "vmafx alias help differs from the vmaf golden transcript"
+fi
+
+# --version is a format contract, not a value: v<major>.<minor>.<patch>
+# optionally followed by the -<N>-g<sha> describe suffix. (C15-03)
+VER_RE='^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+-g[0-9a-f]+)?$'
+"$BIN" --version >"${WORK}/ver.out" 2>"${WORK}/ver.err" ||
+  fail "vmaf --version exited non-zero"
+if [ -s "${WORK}/ver.out" ]; then
+  fail "vmaf --version wrote to stdout"
+fi
+sed -e 's/\r$//' "${WORK}/ver.err" >"${WORK}/ver.norm"
+if ! grep -Eq "$VER_RE" "${WORK}/ver.norm"; then
+  cat "${WORK}/ver.norm" >&2
+  fail "vmaf --version does not match the version format"
+fi
+
+# The alias reports the same version in its own VMAFX form, pinning the
+# ADR-0690 alias behaviour end to end. (C15-02)
+"$ALIAS" --version >"${WORK}/aver.out" 2>"${WORK}/aver.err" ||
+  fail "vmafx --version exited non-zero"
+if [ -s "${WORK}/aver.out" ]; then
+  fail "vmafx --version wrote to stdout"
+fi
+sed -e 's/\r$//' "${WORK}/aver.err" >"${WORK}/aver.norm"
+if ! grep -Eq '^VMAFX v[0-9]+\.[0-9]+\.[0-9]+(-[0-9]+-g[0-9a-f]+)? \(auto-backend, precision=max\)$' \
+  "${WORK}/aver.norm"; then
+  cat "${WORK}/aver.norm" >&2
+  fail "vmafx --version does not match the VMAFX version format"
+fi
+
+# Error transcripts: most refusals are <reason line>, an empty line, then the
+# full usage dump — so the expected file is reason + the help golden, and a
+# drift in either half is caught. The --precision refusal prints its single
+# line and exits without the usage dump (tail = none). $4 = whether line 1
+# embeds argv[0]; $5 = whether the usage dump follows. (C15-07, C15-09,
+# C15-10)
+err_case() {
+  desc=$1
+  want_rc=$2
+  reason=$3
+  argv0_prefix=$4
+  usage_tail=$5
+  shift 5
+  sed -e 's/\r$//' "$GOLDEN" >"${WORK}/golden.norm"
+  if [ "$usage_tail" = usage ]; then
+    { printf '%s\n\n' "$reason"; cat "${WORK}/golden.norm"; } >"${WORK}/expected.err"
+  else
+    printf '%s\n' "$reason" >"${WORK}/expected.err"
+  fi
+  rc=0
+  "$@" >"${WORK}/case.out" 2>"${WORK}/case.err" || rc=$?
+  if [ "$rc" -eq 0 ]; then
+    fail "$desc exited 0, expected $want_rc"
+  fi
+  if [ "$rc" -ne "$want_rc" ]; then
+    fail "$desc exited $rc, expected $want_rc"
+  fi
+  if [ -s "${WORK}/case.out" ]; then
+    fail "$desc wrote to stdout"
+  fi
+  if [ "$argv0_prefix" = argv0 ]; then
+    sed -E -e 's/\r$//' \
+        -e '1s|.*vmaf(\.exe)?: |<app>: |' \
+        -e '3s/^Usage: .* \[options\]$/Usage: <app> [options]/' \
+        "${WORK}/case.err" >"${WORK}/case.norm"
+  else
+    norm_err "${WORK}/case.err" >"${WORK}/case.norm"
+  fi
+  if ! diff -u "${WORK}/expected.err" "${WORK}/case.norm" >"${WORK}/case.diff"; then
+    head -10 "${WORK}/case.diff" >&2
+    fail "$desc transcript drifted"
+  fi
+}
+
+err_case "unparsable --width" 1 \
+  'Invalid argument "nope" for option -w/--width; should be an integer in [0, 2^32-1]' \
+  plain usage "$BIN" --width nope
+
+err_case "negative --width" 1 \
+  'Invalid argument "-1" for option -w/--width; should be a non-negative integer' \
+  plain usage "$BIN" --width -1
+
+err_case "zero --width" 1 \
+  '--width must be > 0' \
+  plain usage "$BIN" --width 0
+
+err_case "unparsable --precision" 1 \
+  '<app>: --precision must be an integer 1..17, or one of: max, full, legacy (got: bogus)' \
+  argv0 none "$BIN" --precision bogus
+
+err_case "unparsable --model" 1 \
+  'Problem parsing model, bad option string "unparseable model".' \
+  plain usage "$BIN" --model 'unparseable model'
+
+# The raw-yuv geometry refusals exit 2 with the declared-vs-actual sizes in
+# the message; a 24x24 8-bit 420 frame is 864 bytes. (C15-09)
+python3 - "$WORK" <<'PY'
+import sys
+from pathlib import Path
+work = Path(sys.argv[1])
+(work / "too_small.yuv").write_bytes(b"\x80" * 100)
+(work / "not_multiple.yuv").write_bytes(b"\x80" * (864 * 2 + 100))
+PY
+
+raw_case() {
+  desc=$1
+  want_rc=$2
+  reason=$3
+  file=$4
+  printf '%s\n' "$reason" >"${WORK}/expected.err"
+  rc=0
+  "$BIN" --reference "$file" --distorted "$file" \
+      --width 24 --height 24 --pixel_format 420 --bitdepth 8 \
+      >"${WORK}/case.out" 2>"${WORK}/case.err" || rc=$?
+  if [ "$rc" -eq 0 ]; then
+    fail "$desc exited 0, expected $want_rc"
+  fi
+  if [ "$rc" -ne "$want_rc" ]; then
+    fail "$desc exited $rc, expected $want_rc"
+  fi
+  if [ -s "${WORK}/case.out" ]; then
+    fail "$desc wrote to stdout"
+  fi
+  sed -e 's/\r$//' -e '1d' "${WORK}/case.err" >"${WORK}/case.extra"
+  if [ -s "${WORK}/case.extra" ]; then
+    fail "$desc printed more than the refusal line on stderr"
+  fi
+  sed -e 's/\r$//' "${WORK}/case.err" >"${WORK}/case.norm"
+  if ! diff -u "${WORK}/expected.err" "${WORK}/case.norm" >"${WORK}/case.diff"; then
+    head -6 "${WORK}/case.diff" >&2
+    fail "$desc refusal text drifted"
+  fi
+}
+
+raw_case "yuv too small for geometry" 2 \
+  'yuv: file too small for declared geometry — need at least 864 bytes for one 24x24 8-bit yuv420p frame, got 100 bytes' \
+  "${WORK}/too_small.yuv"
+
+raw_case "yuv size not a frame multiple" 2 \
+  'yuv: file size mismatch — expected a multiple of 864 bytes for 24x24 8-bit yuv420p, got 1828 bytes (hint: check --bitdepth and --pixel_format; 8-bit frames need 1 byte per sample)' \
+  "${WORK}/not_multiple.yuv"
+
+rm -rf "${WORK}"
+echo "PASS: $0"
diff --git a/core/tools/test/test_vmaf_per_shot.sh b/core/tools/test/test_vmaf_per_shot.sh
index db59d8574d..7aba0d2201 100755
--- a/core/tools/test/test_vmaf_per_shot.sh
+++ b/core/tools/test/test_vmaf_per_shot.sh
@@ -41,6 +41,42 @@ fi
 # 1. --help returns 0.
 "${BIN}" --help >/dev/null
 
+# 1a. Pin per_shot_print_usage() against the golden transcript
+# (issue #3214 row C15-11; ADR-3402): --help serves it on stdout with exit 0,
+# no-args serves the same text on stderr with exit 1. Before this pin the
+# hand-written usage block could change with no test noticing — only its exit
+# code was checked.
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+PS_GOLDEN="${SCRIPT_DIR}/golden/vmaf_per_shot_help.txt"
+"${BIN}" --help >"${WORK}/ps_help.out" 2>"${WORK}/ps_help.err"
+if [ -s "${WORK}/ps_help.err" ]; then
+  echo "test_vmaf_per_shot: --help wrote to stderr" >&2
+  exit 1
+fi
+sed -e 's/\r$//' "${PS_GOLDEN}" >"${WORK}/ps_golden.norm"
+sed -e 's/\r$//' "${WORK}/ps_help.out" >"${WORK}/ps_help.norm"
+if ! diff -u "${WORK}/ps_golden.norm" "${WORK}/ps_help.norm" >"${WORK}/ps_help.diff"; then
+  head -20 "${WORK}/ps_help.diff" >&2
+  echo "test_vmaf_per_shot: usage text drifted from the golden transcript" >&2
+  exit 1
+fi
+rc=0
+"${BIN}" >"${WORK}/ps_noargs.out" 2>"${WORK}/ps_noargs.err" || rc=$?
+if [ "$rc" -ne 1 ]; then
+  echo "test_vmaf_per_shot: no-args exited $rc, expected 1" >&2
+  exit 1
+fi
+if [ -s "${WORK}/ps_noargs.out" ]; then
+  echo "test_vmaf_per_shot: no-args wrote to stdout" >&2
+  exit 1
+fi
+sed -e 's/\r$//' "${WORK}/ps_noargs.err" >"${WORK}/ps_noargs.norm"
+if ! diff -u "${WORK}/ps_golden.norm" "${WORK}/ps_noargs.norm" >"${WORK}/ps_noargs.diff"; then
+  head -20 "${WORK}/ps_noargs.diff" >&2
+  echo "test_vmaf_per_shot: no-args usage text drifted from the golden transcript" >&2
+  exit 1
+fi
+
 # 2. Basic invocation produces a CSV plan with at least one shot row.
 PLAN_CSV="${WORK}/plan.csv"
 "${BIN}" \
diff --git a/core/tools/test/test_vmaf_roi_vpl_usage.sh b/core/tools/test/test_vmaf_roi_vpl_usage.sh
new file mode 100644
index 0000000000..3376f3c467
--- /dev/null
+++ b/core/tools/test/test_vmaf_roi_vpl_usage.sh
@@ -0,0 +1,92 @@
+#!/bin/sh
+# Copyright 2026 luoye-cpu
+# SPDX-License-Identifier: EUPL-1.2
+
+# test_vmaf_roi_vpl_usage.sh — pin the usage text of the vmaf_roi and
+# vmaf_vpl sidecars (issue #3214 rows C15-12, C15-13; ADR-3402).
+#
+# Both print_usage() bodies are hand-written fprintf blocks, so nothing else
+# guards them: a wording or flag change would reach users with no test
+# noticing. vmaf_vpl ships only in Linux SYCL builds (VPL + VA-API), so when
+# the binary is absent the vpl half skips (exit 77) rather than fails; its
+# golden is verified by the Ubuntu SYCL lanes. The vpl golden embeds the
+# VMAF_DEFAULT_MODEL_VERSION default on purpose — a default-model bump must
+# consciously regenerate it.
+#
+# Portability: the vpl "Usage:" line embeds argv[0] and is normalised to
+# "Usage: <app> ..."; Windows CRLF is stripped on both sides. The roi text
+# has no argv[0] placeholder at all.
+set -eu
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+ROI=./tools/vmaf_roi
+VPL=./tools/vmaf_vpl
+WORK="${MESON_BUILD_ROOT:-.}/test_vmaf_roi_vpl_usage.scratch"
+mkdir -p "${WORK}"
+
+fail() {
+  echo "test_vmaf_roi_vpl_usage: $1" >&2
+  exit 1
+}
+
+# --help prints the golden usage on stdout, exits 0, writes nothing to
+# stderr. (C15-12)
+"$ROI" --help >"${WORK}/roi.out" 2>"${WORK}/roi.err" ||
+  fail "vmaf_roi --help exited non-zero"
+if [ -s "${WORK}/roi.err" ]; then
+  fail "vmaf_roi --help wrote to stderr"
+fi
+sed -e 's/\r$//' "$SCRIPT_DIR/golden/vmaf_roi_help.txt" >"${WORK}/roi_golden.norm"
+sed -e 's/\r$//' "${WORK}/roi.out" >"${WORK}/roi.norm"
+if ! diff -u "${WORK}/roi_golden.norm" "${WORK}/roi.norm" >"${WORK}/roi.diff"; then
+  head -20 "${WORK}/roi.diff" >&2
+  fail "vmaf_roi usage text drifted from the golden transcript"
+fi
+
+# vmaf_vpl is built only for Linux SYCL (VPL + VA-API + Level Zero); skip
+# elsewhere. (C15-13)
+if [ ! -x "$VPL" ]; then
+  echo "test_vmaf_roi_vpl_usage: vmaf_vpl not built (non-SYCL build); skipping the vpl half" >&2
+  rm -rf "${WORK}"
+  exit 77 # meson's "skipped"
+fi
+
+# --help prints the golden usage on stderr (argv[0] normalised), exits 0,
+# writes nothing to stdout. (C15-13)
+"$VPL" --help >"${WORK}/vpl.out" 2>"${WORK}/vpl.err" ||
+  fail "vmaf_vpl --help exited non-zero"
+if [ -s "${WORK}/vpl.out" ]; then
+  fail "vmaf_vpl --help wrote to stdout"
+fi
+sed -e 's/\r$//' \
+    -e '1s/^Usage: .* --ref <file> --dis <file> \[options\]$/Usage: <app> --ref <file> --dis <file> [options]/' \
+    "${WORK}/vpl.err" >"${WORK}/vpl.norm"
+sed -e 's/\r$//' "$SCRIPT_DIR/golden/vmaf_vpl_help.txt" >"${WORK}/vpl_golden.norm"
+if ! diff -u "${WORK}/vpl_golden.norm" "${WORK}/vpl.norm" >"${WORK}/vpl.diff"; then
+  head -20 "${WORK}/vpl.diff" >&2
+  fail "vmaf_vpl usage text drifted from the golden transcript"
+fi
+
+# Without --ref/--dis the refusal is the specific first line followed by the
+# same golden usage, exiting 1.
+{ printf '%s\n' 'Error: --ref and --dis are required'; \
+  sed -e 's/\r$//' "$SCRIPT_DIR/golden/vmaf_vpl_help.txt"; } \
+  >"${WORK}/vpl_expected.err"
+rc=0
+"$VPL" >"${WORK}/vpl2.out" 2>"${WORK}/vpl2.err" || rc=$?
+if [ "$rc" -eq 0 ]; then
+  fail "vmaf_vpl without --ref/--dis exited 0"
+fi
+if [ "$rc" -ne 1 ]; then
+  fail "vmaf_vpl without --ref/--dis exited $rc, expected 1"
+fi
+sed -e 's/\r$//' \
+    -e '2s/^Usage: .* --ref <file> --dis <file> \[options\]$/Usage: <app> --ref <file> --dis <file> [options]/' \
+    "${WORK}/vpl2.err" >"${WORK}/vpl2.norm"
+if ! diff -u "${WORK}/vpl_expected.err" "${WORK}/vpl2.norm" >"${WORK}/vpl2.diff"; then
+  head -10 "${WORK}/vpl2.diff" >&2
+  fail "vmaf_vpl missing-required transcript drifted"
+fi
+
+rm -rf "${WORK}"
+echo "PASS: $0"
diff --git a/docs/adr/3402-cli-text-golden-pins.md b/docs/adr/3402-cli-text-golden-pins.md
new file mode 100644
index 0000000000..1ab90e828c
--- /dev/null
+++ b/docs/adr/3402-cli-text-golden-pins.md
@@ -0,0 +1,90 @@
+<!-- markdownlint-disable MD013 MD060 -->
+
+# ADR-3402: User-facing CLI text is pinned against golden transcripts
+
+- **Status**: Accepted
+- **Date**: 2026-11-08
+- **Deciders**: lusoris
+- **Tags**: `testing`, `cli`, `tools`
+
+## Context
+
+The repository gap audit ([issue #3214](https://github.com/VMAFx/vmafx/issues/3214),
+rows C15-01..C15-13, recorded 2026-10-13) found that the text a user actually
+reads — the `vmaf`/`vmafx` help, the `--version` output, the usage blocks of
+the `vmaf_roi`/`vmaf_vpl`/`vmaf-perShot` sidecars, and the option-error and
+geometry-error transcripts — could change without any test noticing. The
+closest guards miss it: the codegen unit tests
+(`scripts/codegen/tests/test_vmafx_api_options.py`) shape synthetic fixtures,
+not what a built binary serves; `dnn/test_cli.sh` greps three flag strings;
+the error-path tests assert exit codes and single substrings.
+
+Two families of text exist. The `vmaf` help and option tables are generated
+(`core/tools/cli_options.gen.inc`, ADR-1852), so a codegen drift guard could
+cover them — but it would still not verify the bytes the binary serves, nor
+the argv[0] head, nor the alias behaviour. The sidecar usage blocks are
+hand-written `fprintf` literals with no generation step at all; only an
+end-to-end transcript pin can guard those.
+
+## Decision
+
+- The user-facing text of the CLI tools is pinned end to end by fast-suite
+  tests that run the real binaries and diff their output against golden
+  transcripts stored under `core/tools/test/golden/`:
+  - `test_vmaf_cli_text_golden.sh` — `vmaf --help` (full transcript), the
+    `--version` format on both binaries, the `vmafx` alias behaviour
+    (byte-identical help modulo argv[0]; its own `VMAFX ... precision=max`
+    version line), the option-error transcripts (`--width`, `--precision`,
+    `--model`), and the raw-yuv geometry refusals.
+  - `test_vmaf_roi_vpl_usage.sh` — the `vmaf_roi` and `vmaf_vpl` usage
+    blocks; the vpl half skips (exit 77) outside Linux SYCL builds and is
+    verified by the Ubuntu SYCL lanes.
+  - `test_vmaf_per_shot.sh` — the `vmaf-perShot` usage block, on both its
+    `--help` (stdout, exit 0) and no-args (stderr, exit 1) paths.
+- An error transcript is pinned as its reason line plus the full usage dump
+  (every `usage()` refusal ends with `print_usage`), so the help golden and
+  the error cases share one source of truth.
+- The first `Usage:` line embeds `argv[0]`, which varies across platforms
+  and invocation paths; the goldens and the tests normalise it to
+  `Usage: <app> ...`. The `--precision` refusal, which starts with
+  `argv[0]:`, is normalised the same way. Captured output is stripped of
+  `\r` before comparing, because the Windows CRT translates `\n` to CRLF
+  through a pipe.
+- A text change is made by consciously regenerating the golden in the same
+  pull request; the diff then shows the exact user-visible change for
+  review. The `vmaf_vpl` golden embeds the current
+  `VMAF_DEFAULT_MODEL_VERSION` value on purpose: bumping the default model
+  must regenerate it.
+- The `vmaf --version` output is pinned as a format (semver optionally
+  followed by the `-<N>-g<sha>` describe suffix), not a value — the value
+  changes with every commit.
+
+## Alternatives considered
+
+- **Codegen idempotency check only** (regenerate `cli_options.gen.inc` in CI
+  and diff). Rejected as the sole guard: it misses the hand-written sidecar
+  texts, the argv[0]/alias behaviour, and everything the binary prints after
+  codegen — the pin verifies what a user of the built binary actually sees.
+- **Golden transcripts inside the test scripts** (heredocs). Rejected: the
+  189-line help transcript would dominate the scripts and obscure the case
+  logic; separate golden files keep each transcript diffable on its own.
+- **Pin the full `Usage:` line including argv[0]** and run only from fixed
+  paths. Rejected: the same transcript must hold on Linux CI (relative
+  `./tools/vmaf`) and Windows local runs (absolute `.exe` paths), and a
+  pin that only one platform can satisfy is a false failure generator.
+
+## Consequences
+
+- Every wording, flag-name, spacing or exit-code change to the pinned text
+  surfaces as a named test failure (`test_vmaf_cli_text_golden`,
+  `test_vmaf_roi_vpl_usage`, `test_vmaf_per_shot`) instead of reaching
+  users silently.
+- The goldens are regeneratable receipts: after an intended text change,
+  re-run the tool with the normalised invocation and refresh
+  `core/tools/test/golden/`.
+- Closes audit rows C15-01, C15-02, C15-03, C15-07, C15-09, C15-10,
+  C15-11, C15-12 and C15-13 of issue #3214. Rows C15-04/05/06 (JSON Schema,
+  XSD and CSV-column validation) stay open — they need new validation
+  dependencies, which is a separate decision. Row C15-08 no longer applies:
+  master's `test_vmaf_read_error_exit.sh` already greps the user-facing
+  stderr strings (`problem while reading pictures`, `ended before`).
diff --git a/docs/adr/_index_fragments/3402-cli-text-golden-pins.md b/docs/adr/_index_fragments/3402-cli-text-golden-pins.md
new file mode 100644
index 0000000000..7e80b3f3e2
--- /dev/null
+++ b/docs/adr/_index_fragments/3402-cli-text-golden-pins.md
@@ -0,0 +1 @@
+| [ADR-3402](3402-cli-text-golden-pins.md) | The user-facing CLI text (help, `--version` format, option-error and geometry-error transcripts, sidecar usage blocks) is pinned end to end against golden transcripts under `core/tools/test/golden/`, with argv[0] normalised and CRLF stripped; a text change regenerates the golden in the same pull request. | Accepted | testing, cli, tools |

From e02690297f1096c40ae2037643105b624e692b45 Mon Sep 17 00:00:00 2001
From: luoye-cpu <3412829159@qq.com>
Date: Sun, 8 Nov 2026 06:15:56 +0800
Subject: [PATCH 2/2] test(tools): split the roi and vpl usage pins into their
 own tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On review: folding both sidecars into one script made the roi golden a
passenger of the vpl skip — a non-SYCL build reported the whole test as
skipped (exit 77) even though the roi transcript had been checked, so
the roi contract had no independent pass/fail signal in the common
builds. Two registrations change that: test_vmaf_roi_usage runs and
passes everywhere, test_vmaf_vpl_usage keeps the skip for the SYCL-only
binary and is verified by the Ubuntu SYCL lanes.

The ADR now also states the suite truth: the per-shot pin lives in the
slow suite next to the smoke it extends, not in fast.

## Deliverables (ADR-0108)

- [ ] **Research digest**: no digest needed: review-driven split; no behaviour besides the registration boundary changed.
- [ ] **Decision matrix**: no alternatives to weigh: splitting is the reviewer-suggested option that preserves the fast-suite contract without moving the pre-existing slow smoke.
- [ ] **AGENTS.md invariant note**: no rebase-sensitive invariants: one script replaced by two, one registration block rewritten in place.
- [x] **Reproducer / smoke-test command** — `meson test -C build test_vmaf_roi_usage test_vmaf_vpl_usage` (locally: roi PASS, vpl skips 77 on the MinGW build; the meson introspection lists both registrations).
- [ ] **CHANGELOG fragment**: no changelog entry needed: test-only, unmerged PR follow-up.

Signed-off-by: luoye-cpu <3412829159@qq.com>
---
 core/tools/test/meson.build                   | 27 +++++++----
 core/tools/test/test_vmaf_roi_usage.sh        | 43 +++++++++++++++++
 ...oi_vpl_usage.sh => test_vmaf_vpl_usage.sh} | 47 ++++++-------------
 docs/adr/3402-cli-text-golden-pins.md         | 14 ++++--
 4 files changed, 86 insertions(+), 45 deletions(-)
 create mode 100644 core/tools/test/test_vmaf_roi_usage.sh
 rename core/tools/test/{test_vmaf_roi_vpl_usage.sh => test_vmaf_vpl_usage.sh} (53%)

diff --git a/core/tools/test/meson.build b/core/tools/test/meson.build
index 290df06133..e5763fc99c 100644
--- a/core/tools/test/meson.build
+++ b/core/tools/test/meson.build
@@ -334,14 +334,26 @@ test('test_vmaf_cli_text_golden', test_vmaf_cli_text_golden,
      ],
      timeout : 120)
 
-# ADR-3402 — the hand-written usage text of the vmaf_roi / vmaf_vpl sidecars
-# is pinned the same way (issue #3214 rows C15-12/C15-13); the vpl half
-# skips (exit 77) outside Linux SYCL builds, where its golden is verified.
-test_vmaf_roi_vpl_usage = find_program('test_vmaf_roi_vpl_usage.sh')
+# ADR-3402 — the hand-written usage texts of the vmaf_roi / vmaf_vpl
+# sidecars are pinned the same way (issue #3214 rows C15-12/C15-13), as two
+# separate tests so the roi golden is a real PASS in every build; the vpl
+# test skips (exit 77) outside Linux SYCL builds, where its golden is
+# verified.
+test_vmaf_roi_usage = find_program('test_vmaf_roi_usage.sh')
+test('test_vmaf_roi_usage', test_vmaf_roi_usage,
+     suite : ['fast'],
+     depends : [vmaf_roi],
+     workdir : meson.project_build_root(),
+     env: [
+         'MESON_BUILD_ROOT=' + meson.project_build_root(),
+         'MESON_SOURCE_ROOT=' + meson.project_source_root(),
+     ],
+     timeout : 120)
+test_vmaf_vpl_usage = find_program('test_vmaf_vpl_usage.sh')
 if vmaf_vpl_ok
-    test('test_vmaf_roi_vpl_usage', test_vmaf_roi_vpl_usage,
+    test('test_vmaf_vpl_usage', test_vmaf_vpl_usage,
          suite : ['fast'],
-         depends : [vmaf_roi, vmaf_vpl],
+         depends : [vmaf_vpl],
          workdir : meson.project_build_root(),
          env: [
              'MESON_BUILD_ROOT=' + meson.project_build_root(),
@@ -349,9 +361,8 @@ if vmaf_vpl_ok
          ],
          timeout : 120)
 else
-    test('test_vmaf_roi_vpl_usage', test_vmaf_roi_vpl_usage,
+    test('test_vmaf_vpl_usage', test_vmaf_vpl_usage,
          suite : ['fast'],
-         depends : [vmaf_roi],
          workdir : meson.project_build_root(),
          env: [
              'MESON_BUILD_ROOT=' + meson.project_build_root(),
diff --git a/core/tools/test/test_vmaf_roi_usage.sh b/core/tools/test/test_vmaf_roi_usage.sh
new file mode 100644
index 0000000000..0e100818f6
--- /dev/null
+++ b/core/tools/test/test_vmaf_roi_usage.sh
@@ -0,0 +1,43 @@
+#!/bin/sh
+# Copyright 2026 luoye-cpu
+# SPDX-License-Identifier: EUPL-1.2
+
+# test_vmaf_roi_usage.sh — pin the usage text of the vmaf_roi sidecar
+# (issue #3214 row C15-12; ADR-3402).
+#
+# print_usage() is a hand-written fprintf block, so nothing else guards it: a
+# wording or flag change would reach users with no test noticing. The roi
+# half is its own Meson test (split from the vpl half on review) so the
+# golden check is a real PASS in every build instead of being folded into a
+# skip when the SYCL-only vmaf_vpl binary is absent.
+#
+# The roi text has no argv[0] placeholder; Windows CRLF is stripped on both
+# sides.
+set -eu
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+ROI=./tools/vmaf_roi
+WORK="${MESON_BUILD_ROOT:-.}/test_vmaf_roi_usage.scratch"
+mkdir -p "${WORK}"
+
+fail() {
+  echo "test_vmaf_roi_usage: $1" >&2
+  exit 1
+}
+
+# --help prints the golden usage on stdout, exits 0, writes nothing to
+# stderr.
+"$ROI" --help >"${WORK}/roi.out" 2>"${WORK}/roi.err" ||
+  fail "vmaf_roi --help exited non-zero"
+if [ -s "${WORK}/roi.err" ]; then
+  fail "vmaf_roi --help wrote to stderr"
+fi
+sed -e 's/\r$//' "$SCRIPT_DIR/golden/vmaf_roi_help.txt" >"${WORK}/roi_golden.norm"
+sed -e 's/\r$//' "${WORK}/roi.out" >"${WORK}/roi.norm"
+if ! diff -u "${WORK}/roi_golden.norm" "${WORK}/roi.norm" >"${WORK}/roi.diff"; then
+  head -20 "${WORK}/roi.diff" >&2
+  fail "vmaf_roi usage text drifted from the golden transcript"
+fi
+
+rm -rf "${WORK}"
+echo "PASS: $0"
diff --git a/core/tools/test/test_vmaf_roi_vpl_usage.sh b/core/tools/test/test_vmaf_vpl_usage.sh
similarity index 53%
rename from core/tools/test/test_vmaf_roi_vpl_usage.sh
rename to core/tools/test/test_vmaf_vpl_usage.sh
index 3376f3c467..6c4b4db303 100644
--- a/core/tools/test/test_vmaf_roi_vpl_usage.sh
+++ b/core/tools/test/test_vmaf_vpl_usage.sh
@@ -2,57 +2,40 @@
 # Copyright 2026 luoye-cpu
 # SPDX-License-Identifier: EUPL-1.2
 
-# test_vmaf_roi_vpl_usage.sh — pin the usage text of the vmaf_roi and
-# vmaf_vpl sidecars (issue #3214 rows C15-12, C15-13; ADR-3402).
+# test_vmaf_vpl_usage.sh — pin the usage text of the vmaf_vpl sidecar
+# (issue #3214 row C15-13; ADR-3402).
 #
-# Both print_usage() bodies are hand-written fprintf blocks, so nothing else
-# guards them: a wording or flag change would reach users with no test
-# noticing. vmaf_vpl ships only in Linux SYCL builds (VPL + VA-API), so when
-# the binary is absent the vpl half skips (exit 77) rather than fails; its
-# golden is verified by the Ubuntu SYCL lanes. The vpl golden embeds the
-# VMAF_DEFAULT_MODEL_VERSION default on purpose — a default-model bump must
-# consciously regenerate it.
+# print_usage() is a hand-written fprintf block, so nothing else guards it: a
+# wording or flag change would reach users with no test noticing. vmaf_vpl
+# ships only in Linux SYCL builds (VPL + VA-API + Level Zero), so outside
+# them this test skips (exit 77) rather than fails; the golden is verified by
+# the Ubuntu SYCL lanes. The golden embeds the VMAF_DEFAULT_MODEL_VERSION
+# default on purpose — a default-model bump must consciously regenerate it.
 #
-# Portability: the vpl "Usage:" line embeds argv[0] and is normalised to
-# "Usage: <app> ..."; Windows CRLF is stripped on both sides. The roi text
-# has no argv[0] placeholder at all.
+# Portability: the "Usage:" line embeds argv[0] and is normalised to
+# "Usage: <app> ..."; Windows CRLF is stripped on both sides.
 set -eu
 
 SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
-ROI=./tools/vmaf_roi
 VPL=./tools/vmaf_vpl
-WORK="${MESON_BUILD_ROOT:-.}/test_vmaf_roi_vpl_usage.scratch"
+WORK="${MESON_BUILD_ROOT:-.}/test_vmaf_vpl_usage.scratch"
 mkdir -p "${WORK}"
 
 fail() {
-  echo "test_vmaf_roi_vpl_usage: $1" >&2
+  echo "test_vmaf_vpl_usage: $1" >&2
   exit 1
 }
 
-# --help prints the golden usage on stdout, exits 0, writes nothing to
-# stderr. (C15-12)
-"$ROI" --help >"${WORK}/roi.out" 2>"${WORK}/roi.err" ||
-  fail "vmaf_roi --help exited non-zero"
-if [ -s "${WORK}/roi.err" ]; then
-  fail "vmaf_roi --help wrote to stderr"
-fi
-sed -e 's/\r$//' "$SCRIPT_DIR/golden/vmaf_roi_help.txt" >"${WORK}/roi_golden.norm"
-sed -e 's/\r$//' "${WORK}/roi.out" >"${WORK}/roi.norm"
-if ! diff -u "${WORK}/roi_golden.norm" "${WORK}/roi.norm" >"${WORK}/roi.diff"; then
-  head -20 "${WORK}/roi.diff" >&2
-  fail "vmaf_roi usage text drifted from the golden transcript"
-fi
-
 # vmaf_vpl is built only for Linux SYCL (VPL + VA-API + Level Zero); skip
-# elsewhere. (C15-13)
+# elsewhere.
 if [ ! -x "$VPL" ]; then
-  echo "test_vmaf_roi_vpl_usage: vmaf_vpl not built (non-SYCL build); skipping the vpl half" >&2
+  echo "test_vmaf_vpl_usage: vmaf_vpl not built (non-SYCL build); skipping" >&2
   rm -rf "${WORK}"
   exit 77 # meson's "skipped"
 fi
 
 # --help prints the golden usage on stderr (argv[0] normalised), exits 0,
-# writes nothing to stdout. (C15-13)
+# writes nothing to stdout.
 "$VPL" --help >"${WORK}/vpl.out" 2>"${WORK}/vpl.err" ||
   fail "vmaf_vpl --help exited non-zero"
 if [ -s "${WORK}/vpl.out" ]; then
diff --git a/docs/adr/3402-cli-text-golden-pins.md b/docs/adr/3402-cli-text-golden-pins.md
index 1ab90e828c..f91899292e 100644
--- a/docs/adr/3402-cli-text-golden-pins.md
+++ b/docs/adr/3402-cli-text-golden-pins.md
@@ -36,11 +36,14 @@ end-to-end transcript pin can guard those.
     (byte-identical help modulo argv[0]; its own `VMAFX ... precision=max`
     version line), the option-error transcripts (`--width`, `--precision`,
     `--model`), and the raw-yuv geometry refusals.
-  - `test_vmaf_roi_vpl_usage.sh` — the `vmaf_roi` and `vmaf_vpl` usage
-    blocks; the vpl half skips (exit 77) outside Linux SYCL builds and is
-    verified by the Ubuntu SYCL lanes.
+  - `test_vmaf_roi_usage.sh` and `test_vmaf_vpl_usage.sh` — the hand-written
+    `vmaf_roi` and `vmaf_vpl` usage blocks, as two separate tests so the roi
+    golden is a real PASS in every build; the vpl test skips (exit 77)
+    outside Linux SYCL builds and is verified by the Ubuntu SYCL lanes.
   - `test_vmaf_per_shot.sh` — the `vmaf-perShot` usage block, on both its
-    `--help` (stdout, exit 0) and no-args (stderr, exit 1) paths.
+    `--help` (stdout, exit 0) and no-args (stderr, exit 1) paths. This one
+    test sits in the `slow` suite, where the sidecar smoke it extends already
+    runs; the other pins are in `fast`.
 - An error transcript is pinned as its reason line plus the full usage dump
   (every `usage()` refusal ends with `print_usage`), so the help golden and
   the error cases share one source of truth.
@@ -77,7 +80,8 @@ end-to-end transcript pin can guard those.
 
 - Every wording, flag-name, spacing or exit-code change to the pinned text
   surfaces as a named test failure (`test_vmaf_cli_text_golden`,
-  `test_vmaf_roi_vpl_usage`, `test_vmaf_per_shot`) instead of reaching
+  `test_vmaf_roi_usage`, `test_vmaf_vpl_usage`, `test_vmaf_per_shot`)
+  instead of reaching
   users silently.
 - The goldens are regeneratable receipts: after an intended text change,
   re-run the tool with the normalised invocation and refresh