From ec180fad7bc1b056ba2d9faa7eb5033c10e9ad2f Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Fri, 18 Sep 2026 22:16:42 +0530
Subject: [PATCH 1/2] ci(validation): run consumer tests from the validation
 entry point

---
 .github/workflows/tests.yml |  6 ++----
 README.md                   |  5 +++--
 tests/validate.sh           | 22 +++++++++++++++++++++-
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index a96020f..9ca773c 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -17,16 +17,14 @@ jobs:
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
-      - name: Validate repository baseline
-        run: ./tests/validate.sh
       - name: Set up Python
         uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.13"
       - name: Install the reference consumer
         run: python -m pip install ".[dev]"
-      - name: Run consumer tests
-        run: python -m pytest
+      - name: Run authoritative consumer validation
+        run: ./tests/validate.sh
 
   optional-integrations:
     runs-on: macos-latest
diff --git a/README.md b/README.md
index f6993ca..743dff9 100644
--- a/README.md
+++ b/README.md
@@ -97,11 +97,12 @@ profile boundary.
 
 ## Development
 
-Install the development extra and run the focused suite:
+Install the development extra and run the authoritative consumer gate (which
+checks the installed environment and runs the complete suite, including the
+documented-command smoke tests):
 
 ```bash
 python -m pip install ".[dev]"
-python -m pytest
 ./tests/validate.sh
 ```
 
diff --git a/tests/validate.sh b/tests/validate.sh
index 3b06005..d294936 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -21,4 +21,24 @@ for file in "${required_files[@]}"; do
   }
 done
 
-printf 'Repository baseline is present.\n'
+command -v python >/dev/null || {
+  printf 'Python is required; install the project development extra first.\n' >&2
+  exit 1
+}
+
+python - <<'PY'
+from importlib.metadata import PackageNotFoundError, version
+
+for distribution in ("base-cli-demo", "base-cli", "pytest"):
+    try:
+        installed_version = version(distribution)
+    except PackageNotFoundError as exc:
+        raise SystemExit(
+            f"Missing installed distribution {distribution!r}; "
+            'run `python -m pip install ".[dev]"` first.'
+        ) from exc
+    print(f"Found {distribution} {installed_version}.")
+PY
+
+printf 'Running the complete consumer and documentation-command suite.\n'
+exec python -m pytest -q

From 81d518122dade09dc69d905461506740d9bf32a3 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Sat, 19 Sep 2026 16:26:02 +0530
Subject: [PATCH 2/2] ci: make validation fail fast and authoritative

---
 .github/workflows/compatibility.yml | 4 +---
 tests/validate.sh                   | 1 +
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/compatibility.yml b/.github/workflows/compatibility.yml
index c7d2940..ff26f3e 100644
--- a/.github/workflows/compatibility.yml
+++ b/.github/workflows/compatibility.yml
@@ -50,8 +50,6 @@ jobs:
         run: python -c 'import base_cli_demo, pathlib; root = pathlib.Path.cwd().resolve(); assert root not in pathlib.Path(base_cli_demo.__file__).resolve().parents'
       - name: Validate the repository baseline
         run: ./tests/validate.sh
-      - name: Run installed-wheel compatibility tests
-        run: python -m pytest -q
 
   upcoming:
     if: ${{ github.event_name == 'workflow_dispatch' && inputs.upcoming_base_cli != '' }}
@@ -73,4 +71,4 @@ jobs:
       - name: Install the demo wheel without source dependencies
         run: python -m pip install --no-deps dist/*.whl
       - name: Run the non-blocking upcoming compatibility check
-        run: python -m pytest -q
+        run: ./tests/validate.sh
diff --git a/tests/validate.sh b/tests/validate.sh
index d294936..b8b2d10 100755
--- a/tests/validate.sh
+++ b/tests/validate.sh
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+set -euo pipefail
 
 required_files=(
   README.md