spec-check: a mismatched local openspec is bypassed for npx at the pin, refused only when npx cannot run

Council pass 10 Q3 (seat claude-opus-5.5), adopted over the coordinator's own §5 hold. The refusal's
premise — a validator at another release validates a different contract — argues against USING the
mismatched binary, not against running the pinned one, and `npx` runs the pinned one in the same
command. Refusing outright made `just preflight` fail for a contributor whose global openspec is
newer until they downgrade a tool they use elsewhere, which teaches people to skip preflight.

New order: local == pin -> use it; else npx at the pin (one stderr line names the ignored version
and the pinned one); mismatched local AND npx unavailable -> exit 2 (a wrong-version tool on PATH is
never reported as "no tool here"); nothing at all -> SKIPPED locally, exit 1 under CI. The validate
exit code is still exec'd, never laundered. RED-first test with a fake binary and a fake npx that
logs its arguments; the earlier offline mismatch test still expects exit 2. 15 gate tests; shellcheck
clean; `just spec-check` 26/26; docs strict.

Author: NetDevAutomate

Justfile

@@ -6,8 +6,9 @@ set shell := ["bash", "-cu"]
 export PYTHONWARNINGS := "ignore:builtin type swigvarlink has no __module__ attribute:DeprecationWarning"
 
 # The one OpenSpec CLI release the repository validates against. `scripts/openspec-cli.sh`
-# resolves it (a matching local binary, else npx at exactly this version) and refuses any other
-# local version; `just spec-check` and the release gate both go through that script. Bumping
+# resolves it: a local binary at exactly this version, else npx at exactly this version (a local
+# binary at another version is never used — bypassed with a notice, or refused when npx cannot run);
+# `just spec-check` and the release gate both go through that script. Bumping
 # this is a deliberate commit: a new release can add validation rules (1.14 promoted the
 # >500-character requirement finding to a warning, which is how 84 of them appeared at once).
 export OPENSPEC_VERSION := "1.14.1"

docs/contributor-conventions.md

@@ -70,8 +70,9 @@ small fix with a test goes straight to a pull request.
    `spec-check` until it was added), so the flag is the reviewer's cue that "no delta" was a choice.
 3. Validate the structure with `openspec validate --specs --all --strict`: every warning fails, so
    the output is a gate and not a list nobody reads. The recipe resolves the CLI through `scripts/openspec-cli.sh` at the one pinned
-   release (`OPENSPEC_VERSION` in the `Justfile`; a local `openspec` at any other version is
-   refused, otherwise `npx` fetches the pinned one). Without node or the CLI the recipe prints
+   release (`OPENSPEC_VERSION` in the `Justfile`): a local `openspec` at that version is used; at
+   any other version it is never used -- `npx` validates with the pinned one and says so, or the
+   recipe refuses when `npx` cannot run. Without node or the CLI the recipe prints
    `SKIPPED` and exits 0 on your machine -- a skip is not a pass -- and the `spec-check` job in CI,
    which runs the same recipe, fails on the same absence:
 

packages/studyloop/tests/test_spec_check_gate.py

@@ -267,3 +267,30 @@ def test_release_check_runs_spec_check() -> None:
         line for line in _justfile().splitlines() if line.startswith("release-check:")
     )
     assert "spec-check" in recipe_line.split()
+
+
+def test_a_mismatched_local_binary_is_bypassed_for_npx_at_the_pin_when_npx_can_run(
+    tmp_path: Path,
+) -> None:
+    """Pass 10 Q3 (seat claude-opus-5.5, adopted over the coordinator's §5 hold): the mismatched
+    binary is never USED, but the pinned contract is still validated — by npx — with one stderr
+    line naming both versions. Refusal (exit 2) is kept for the case where npx cannot run, so a
+    wrong-version tool on PATH is never reported as 'no tool here'."""
+    fake_bin = _fake_bin(
+        tmp_path,
+        "openspec",
+        'if [ "$1" = --version ]; then echo 9.9.9; exit 0; fi\necho "WRONG BINARY RAN"; exit 0\n',
+    )
+    npx_log = tmp_path / "npx-args.txt"
+    (fake_bin / "npx").write_text(
+        f'#!/bin/sh\nprintf "%s " "$@" >> "{npx_log}"\n'
+        'if [ "$3" = --version ]; then echo 1.14.1; exit 0; fi\necho "pinned ran"; exit 0\n',
+        encoding="utf-8",
+    )
+    (fake_bin / "npx").chmod(0o755)
+    env = {"PATH": f"{fake_bin}:/usr/bin:/bin", "OPENSPEC_VERSION": "1.14.1", "HOME": str(tmp_path)}
+    proc = _resolver(["validate", "--specs", "--all", "--strict"], env)
+    assert proc.returncode == 0, proc.stdout + proc.stderr
+    assert "pinned ran" in proc.stdout and "WRONG BINARY RAN" not in proc.stdout
+    assert "9.9.9" in proc.stderr and "1.14.1" in proc.stderr
+    assert "@fission-ai/openspec@1.14.1" in npx_log.read_text(encoding="utf-8")

scripts/openspec-cli.sh

@@ -3,20 +3,23 @@
 #
 # Usage: scripts/openspec-cli.sh <openspec args…>
 #
-# Resolution (plan 7, ARBITRATION-pass9.md §4 Q4/Q6, §8.2 R4):
+# Resolution (plan 7, ARBITRATION-pass9.md §4 Q4/Q6, §8.2 R4; order revised by pass 10 Q3):
 #   1. A local `openspec` on PATH is used ONLY if `openspec --version` equals the pin
-#      ($OPENSPEC_VERSION, exported by the Justfile). A different version is REFUSED — a validator
-#      at another release may apply other rules, so its "pass" would be about a different contract.
-#   2. Otherwise `npx --yes @fission-ai/openspec@$OPENSPEC_VERSION` (exact top-level pin; the
-#      package's own dependencies float on caret ranges — the same residual the repo accepts for
-#      `uv tool run pip-audit@…`).
-#   3. If neither can run: on a contributor's machine print SKIPPED and exit 0 — a gate that fails for
-#      a reason nobody is working on teaches people to ignore it (Justfile, release-check notes) —
-#      but under CI ($CI set, as GitHub sets it) exit 1: a skip is not a pass, and CI is where the
-#      gate is enforced.
+#      ($OPENSPEC_VERSION, exported by the Justfile). A validator at another release applies other
+#      rules, so its "pass" would be about a different contract: a mismatched binary is never used.
+#   2. Otherwise `npx --yes @fission-ai/openspec@$OPENSPEC_VERSION` validates the pinned contract in
+#      the same command (exact top-level pin; the package's own dependencies float on caret ranges —
+#      the residual the repo also accepts for `uv tool run pip-audit@…`). When a mismatched local
+#      binary was bypassed, one stderr line says so, naming both versions.
+#   3. npx cannot run AND a mismatched local binary exists: exit 2 — a wrong-version tool on PATH is
+#      a fact the reader must see, never reported as "no tool here".
+#   4. Nothing at all: on a contributor's machine print SKIPPED and exit 0 — a gate that fails for a
+#      reason nobody is working on teaches people to ignore it — but under CI ($CI set, as GitHub
+#      sets it) exit 1: a skip is not a pass, and CI is where the gate is enforced.
 #
 # Fetch is separated from validate: `--version` is run first so an environmental failure (no node,
-# npx cannot resolve) is reported as such, and the validation's own exit code is the gate.
+# npx cannot resolve) is reported as such, and the validation's own exit code is the gate — it is
+# exec'd, never laundered.
 #
 # OPENSPEC_TELEMETRY=0 is set so an npx-fetched CLI does not start reporting usage from a machine
 # whose owner never installed openspec. OPENSPEC_NO_NPX=1 disables step 2 (tests use it to stay
@@ -28,41 +31,42 @@ set -euo pipefail
 export OPENSPEC_TELEMETRY=0
 
 pointer="see docs/contributor-conventions.md § OpenSpec"
+local_version=""      # what a local binary reported, when one is on PATH
+local_mismatch=""     # non-empty when that version is not the pin
 
-run_local() {
-    local found
-    found="$(openspec --version 2>/dev/null | tr -d '[:space:]' || true)"
-    if [[ -z "$found" ]]; then
+if command -v openspec >/dev/null 2>&1; then
+    local_version="$(openspec --version 2>/dev/null | tr -d '[:space:]' || true)"
+    if [[ -z "$local_version" ]]; then
         echo "openspec-cli: a local openspec is on PATH but printed no version; ignoring it" >&2
-        return 1
-    fi
-    if [[ "$found" != "$OPENSPEC_VERSION" ]]; then
-        echo "openspec-cli: local openspec is $found but the repository pins $OPENSPEC_VERSION;" >&2
-        echo "openspec-cli: refusing to use it (uninstall it, or install $OPENSPEC_VERSION); $pointer" >&2
-        exit 2
+    elif [[ "$local_version" == "$OPENSPEC_VERSION" ]]; then
+        exec openspec "$@"
+    else
+        local_mismatch=1
     fi
-    exec openspec "$@"
-}
+fi
 
-run_npx() {
-    if [[ -n "${OPENSPEC_NO_NPX:-}" ]]; then
-        return 1
-    fi
-    if ! command -v npx >/dev/null 2>&1; then
-        return 1
-    fi
+npx_ok=""
+if [[ -z "${OPENSPEC_NO_NPX:-}" ]] && command -v npx >/dev/null 2>&1; then
     # fetch first: an unresolvable package is environmental, not a validation result
-    if ! npx --yes "@fission-ai/openspec@$OPENSPEC_VERSION" --version >/dev/null 2>&1; then
-        return 1
+    if npx --yes "@fission-ai/openspec@$OPENSPEC_VERSION" --version >/dev/null 2>&1; then
+        npx_ok=1
     fi
-    exec npx --yes "@fission-ai/openspec@$OPENSPEC_VERSION" "$@"
-}
+fi
 
-if command -v openspec >/dev/null 2>&1; then
-    run_local "$@" || true   # a matching binary execs; a mismatch exits 2; a silent one falls through
+if [[ -n "$npx_ok" ]]; then
+    if [[ -n "$local_mismatch" ]]; then
+        echo "openspec-cli: local openspec $local_version ignored (the repository pins $OPENSPEC_VERSION);" >&2
+        echo "openspec-cli: validating with $OPENSPEC_VERSION via npx; $pointer" >&2
+    fi
+    exec npx --yes "@fission-ai/openspec@$OPENSPEC_VERSION" "$@"
 fi
 
-run_npx "$@" || true
+if [[ -n "$local_mismatch" ]]; then
+    echo "openspec-cli: local openspec is $local_version but the repository pins $OPENSPEC_VERSION," >&2
+    echo "openspec-cli: and npx cannot supply the pinned release here; refusing to use the local one" >&2
+    echo "openspec-cli: (install $OPENSPEC_VERSION, or make node available); $pointer" >&2
+    exit 2
+fi
 
 if [[ -n "${CI:-}" ]]; then
     echo "openspec-cli: openspec $OPENSPEC_VERSION is not available (no matching local binary, npx unavailable);" >&2