sobres 1.1.0__tar.gz

sobres-1.1.0/.claude/hooks/commit-gate.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Claude Code PreToolUse hook: before any `git commit` runs from a Bash tool call, run the
+# same gate CI runs (ruff check, ruff format --check, mypy --strict, actionlint). Exit 2 blocks the
+# commit and hands the output back to the agent, so a red PR is caught before it exists.
+#
+# Reads the tool call as JSON on stdin; only acts when the command contains "git commit".
+set -uo pipefail
+payload=$(cat)
+command=$(printf '%s' "$payload" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("tool_input", {}).get("command", ""))' 2>/dev/null || true)
+case "$command" in
+  *"git commit"*) ;;
+  *) exit 0 ;;
+esac
+root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+cd "$root" || exit 0
+fail=0
+run() {
+  local name=$1; shift
+  if ! output=$("$@" 2>&1); then
+    printf '\n[commit gate] %s failed:\n%s\n' "$name" "$output" >&2
+    fail=1
+  fi
+}
+run "ruff check" ruff check .
+run "ruff format --check" ruff format --check .
+run "mypy --strict" python -m mypy
+if command -v pre-commit >/dev/null 2>&1; then
+  run "actionlint" pre-commit run actionlint --all-files
+fi
+if [ "$fail" -ne 0 ]; then
+  printf '\n[commit gate] fix the findings above (ruff format . fixes formatting), then commit again.\n' >&2
+  exit 2
+fi
+exit 0

sobres-1.1.0/.claude/settings.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/commit-gate.sh",
+            "timeout": 600
+          }
+        ]
+      }
+    ]
+  }
+}

sobres-1.1.0/.dockerignore

@@ -0,0 +1,24 @@
+# Only sources reach the build; nothing from a developer's machine does.
+.git
+.github
+.venv
+venv
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+dist
+build
+*.egg-info
+frontend/node_modules
+src/sobres/api/static
+legacy_code
+openspec
+docs
+site
+tests
+.env
+*.toml.bak

sobres-1.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Recorded payload digests cover exact bytes, including vendor line endings.
+tests/fixtures/** -text

sobres-1.1.0/.github/ISSUE_TEMPLATE/hosting-inquiry.yml

@@ -0,0 +1,38 @@
+name: Hosting inquiry
+description: Ask about running sobres for you. This issue is public; do not include anything confidential.
+title: "Hosting inquiry: "
+labels: ["hosting-inquiry"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **This issue is public.** Anyone can read it.
+        Do not paste API keys, account numbers, statements, holdings, or anything else you would not publish.
+
+        sobres is a single-user research tool. An inquiry is a conversation about whether
+        running it for you makes sense; it is not an order, a service-level agreement,
+        a payment contract, or a multi-tenant product, and it is not investment advice.
+  - type: dropdown
+    id: shape
+    attributes:
+      label: What are you looking for?
+      options:
+        - Help running the container myself
+        - Someone to run it for me
+        - Something else (describe below)
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Context
+      description: Where would it run, for how many people, and what would you use it for? Keep it general.
+    validations:
+      required: true
+  - type: checkboxes
+    id: confirm
+    attributes:
+      label: Confirm
+      options:
+        - label: I understand this issue is public and I have not included credentials, financial records or other confidential information.
+          required: true

sobres-1.1.0/.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "ci"
+    groups:
+      # One PR per week for routine action bumps rather than five.
+      actions:
+        patterns: ["*"]
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "deps"
+    groups:
+      dev-dependencies:
+        dependency-type: development
+        patterns: ["*"]
+    # Runtime dependency majors are a deliberate decision, not a weekly chore.
+    ignore:
+      - dependency-name: "*"
+        update-types: ["version-update:semver-major"]

sobres-1.1.0/.github/pull_request_template.md

@@ -0,0 +1,26 @@
+## What
+
+<!-- One or two sentences. What does this change do? -->
+
+## OpenSpec change
+
+<!-- Which change under openspec/changes/ does this implement? Which tasks? -->
+- Change: `openspec/changes/____`
+- Tasks completed: <!-- e.g. B1, B2, B3 -->
+
+## Scenarios covered
+
+<!-- List the spec scenarios this PR implements, and the test proving each. -->
+| Scenario | Test |
+|---|---|
+|  |  |
+
+## Checklist
+
+- [ ] Every new behavior has a scenario in a spec delta
+- [ ] Every scenario has a test that references it
+- [ ] `pytest -m "not network"` passes offline
+- [ ] `ruff check`, `ruff format --check`, and `mypy` are clean
+- [ ] No business logic added to `cli/`; no I/O added to `core/`
+- [ ] No bare periods-per-year literals (use `core/conventions.py`)
+- [ ] Task boxes checked off in the change's `tasks.md`

sobres-1.1.0/.github/scripts/check_release.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""Decide whether the current commit should be published.
+
+PyPI versions are immutable: re-uploading an existing version is a hard error,
+not an overwrite. So "publish on every push to main" can only mean "publish when
+the version declared in ``__about__.py`` is not yet on the index".
+
+Writes ``version``, ``target``, ``publish`` and ``reason`` as ``KEY=value`` lines on stdout,
+which the workflow appends to ``$GITHUB_OUTPUT``.
+
+stdout is therefore a machine interface: it carries ONLY ``key=value`` lines.
+Every human-facing message goes to stderr. ``$GITHUB_OUTPUT`` rejects any line
+that is not ``key=value``, so a stray informational print on stdout fails the
+whole job -- which is exactly what happened on the first push to ``main``.
+``tests/test_release_script.py`` enforces the contract.
+
+Run locally to see what the next push to main would do::
+
+    python .github/scripts/check_release.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+import tomllib
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+ABOUT = REPO_ROOT / "src" / "sobres" / "__about__.py"
+PYPROJECT = REPO_ROOT / "pyproject.toml"
+CHANGELOG = REPO_ROOT / "CHANGELOG.md"
+
+INDEXES = {
+    "pypi": "https://pypi.org/pypi/{name}/json",
+    "testpypi": "https://test.pypi.org/pypi/{name}/json",
+}
+
+# PEP 440, restricted to the subset this project actually uses.
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+(?:(?:a|b|rc)\d+)?(?:\.dev\d+)?$")
+
+
+def note(message: str) -> None:
+    """Human-facing progress line. stderr, never stdout -- stdout is $GITHUB_OUTPUT."""
+    print(message, file=sys.stderr)
+
+
+def emit(key: str, value: str) -> None:
+    """The only writer to stdout: one ``key=value`` line for $GITHUB_OUTPUT."""
+    print(f"{key}={value}")
+
+
+def fail(message: str) -> None:
+    """Emit a GitHub Actions error annotation and exit non-zero."""
+    print(f"::error::{message}", file=sys.stderr)
+    raise SystemExit(1)
+
+
+def read_version() -> str:
+    match = re.search(
+        r'^__version__\s*=\s*"([^"]+)"', ABOUT.read_text(encoding="utf-8"), re.MULTILINE
+    )
+    if not match:
+        fail(f"Could not find __version__ in {ABOUT.relative_to(REPO_ROOT)}")
+        raise AssertionError("unreachable")  # pragma: no cover
+    return match.group(1)
+
+
+def read_dist_name() -> str:
+    return str(tomllib.loads(PYPROJECT.read_text(encoding="utf-8"))["project"]["name"])
+
+
+def released_versions(dist_name: str, target: str) -> set[str] | None:
+    """Return every version on the index, or ``None`` if the project is new."""
+    url = INDEXES[target].format(name=dist_name)
+    request = urllib.request.Request(url, headers={"Accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            return set(json.load(response)["releases"])
+    except urllib.error.HTTPError as exc:
+        if exc.code == 404:
+            # First ever release: the project does not exist on the index yet.
+            return None
+        fail(f"{target} returned HTTP {exc.code} for {dist_name}")
+    except urllib.error.URLError as exc:
+        # A network blip must not silently look like "nothing is published",
+        # which would re-publish an existing version and fail at upload.
+        fail(f"Could not reach {target}: {exc.reason}")
+    raise AssertionError("unreachable")  # pragma: no cover
+
+
+def main() -> None:
+    target = os.environ.get("TARGET", "pypi")
+    if target not in INDEXES:
+        fail(f"TARGET must be one of {sorted(INDEXES)}, got {target!r}")
+
+    version = read_version()
+    if not VERSION_RE.match(version):
+        fail(
+            f"Version {version!r} is not a valid release version "
+            f"(expected e.g. 1.2.3, 1.2.3rc1 or 1.2.3.dev0)"
+        )
+
+    dist_name = read_dist_name()
+    existing = released_versions(dist_name, target)
+
+    if existing is None:
+        note(f"{dist_name} is not on {target} yet -- this would be the first release.")
+        publish = True
+    elif version in existing:
+        note(f"{dist_name} {version} is already on {target}; nothing to publish.")
+        publish = False
+    else:
+        note(f"{dist_name} {version} is not on {target}; it will be published.")
+        publish = True
+
+    # Release discipline: a version that ships must be described. Checked only
+    # when actually publishing, so ordinary pushes are never blocked by it.
+    if publish and CHANGELOG.exists():
+        changelog = CHANGELOG.read_text(encoding="utf-8")
+        if f"## [{version}]" not in changelog and f"## {version}" not in changelog:
+            fail(
+                f"CHANGELOG.md has no section for {version}. "
+                f"Add a '## [{version}]' heading describing the release."
+            )
+
+    emit("version", version)
+    emit("target", target)
+    emit("publish", str(publish).lower())
+    emit("reason", "new-version" if publish else "already-published")
+
+
+if __name__ == "__main__":
+    main()

sobres-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,353 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  # Callable by release.yml so a release runs the exact same gates, not a copy
+  # of them that can drift.
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  FORCE_COLOR: "1"
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  lint:
+    name: Lint and format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - name: ruff check
+        run: ruff check --output-format=github .
+      - name: ruff format
+        run: ruff format --check --diff .
+
+      - name: Lint GitHub Actions workflows
+        # These workflows are code, and they fail in a way no unit test can
+        # catch: an invalid expression is rejected before any job starts, so the
+        # run reports failure with zero jobs and no log to read.
+        # Pinned release download rather than a third-party action or a
+        # curl-piped-to-bash installer.
+        env:
+          ACTIONLINT_VERSION: "1.7.7"
+        run: |
+          curl -sSfL -o actionlint.tar.gz \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          tar xzf actionlint.tar.gz actionlint
+          ./actionlint -color
+
+  typecheck:
+    name: Type check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - name: mypy --strict
+        run: mypy
+
+  test:
+    name: Test ${{ matrix.python-version }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          # Cross-platform coverage on the primary interpreter only. Path
+          # handling and the on-disk cache are the parts that break on Windows.
+          - os: macos-latest
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]"
+      - name: pytest
+        # Network-marked tests hit live providers; a vendor outage must never
+        # turn this repo red. Run them deliberately with `pytest -m network`.
+        run: pytest -m "not network" --cov --cov-report=xml --cov-report=term-missing --cov-fail-under=90
+
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+  frontend:
+    name: Frontend (types, client drift, bundle budget)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: pip install -e ".[dev]"
+      - name: The committed OpenAPI document matches the registry
+        # The TypeScript client is generated from this file; drift is a build
+        # failure here rather than a runtime one in the browser.
+        run: python scripts/export_openapi.py --check
+      - run: npm ci
+        working-directory: frontend
+      - name: The generated client matches the OpenAPI document
+        run: npm run check:client
+        working-directory: frontend
+      - name: Type check, build, bundle budget
+        # `build` runs tsc --strict, vite, then the 300 KB gzip gate.
+        run: npm run build
+        working-directory: frontend
+      - name: Upload the built SPA
+        uses: actions/upload-artifact@v7
+        with:
+          name: frontend-static
+          path: src/sobres/api/static/
+          if-no-files-found: error
+
+  build:
+    name: Build and verify distributions
+    needs: [frontend]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # setuptools-scm-style tooling and changelog checks want real history.
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Fetch the built SPA
+        # The wheel ships the frontend at sobres/api/static so `pip install
+        # sobres[web]` needs no Node.
+        uses: actions/download-artifact@v8
+        with:
+          name: frontend-static
+          path: src/sobres/api/static/
+
+      - run: pip install build twine
+      - name: Build sdist and wheel
+        run: python -m build
+
+      - name: The wheel carries the SPA
+        run: unzip -l dist/*.whl | grep -q "sobres/api/static/index.html"
+
+      - name: twine check
+        run: twine check --strict dist/*
+
+      - name: Install the base wheel, no extras, in a clean environment
+        # `pip install sobres` with no extras is what most users get, and until
+        # now nothing tested it: every other job installs `.[dev]` and the job
+        # below installs `[web]`. Registering commands imports every module under
+        # cli/commands/, so a single module-scope import of an optional
+        # dependency breaks the whole CLI, `--version` included. That shipped.
+        env:
+          SOBRES_CONFIG_FILE: /tmp/base-home/config.toml
+          SOBRES_DB_URL: sqlite:////tmp/base-home/sobres.db
+          SOBRES_FIXTURE_DIR: ${{ github.workspace }}/tests/fixtures
+        run: |
+          python -m venv /tmp/smoke-base
+          /tmp/smoke-base/bin/pip install --upgrade pip
+          /tmp/smoke-base/bin/pip install "$(ls dist/*.whl)"
+          # The check is only meaningful if the extra is genuinely absent.
+          if /tmp/smoke-base/bin/python -c "import fastapi" 2>/dev/null; then
+            echo "::error::fastapi is installed in the base environment; this job proves nothing"
+            exit 1
+          fi
+          /tmp/smoke-base/bin/sobres --version
+          /tmp/smoke-base/bin/sobres --help > /dev/null
+          /tmp/smoke-base/bin/sobres init --non-interactive --offline
+          /tmp/smoke-base/bin/sobres doctor --offline
+          /tmp/smoke-base/bin/sobres data prices AAPL MSFT --start 2020-01-01 --end 2020-03-31 \
+            --format csv | head -3
+
+      - name: Install the built wheel in a clean environment
+        # Proves the artifact users actually download works -- catches missing
+        # package data, a broken entry point, or an import that only resolves
+        # from the source tree.
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --upgrade pip
+          /tmp/smoke/bin/pip install "$(ls dist/*.whl)[web]"
+          /tmp/smoke/bin/sobres --version
+          /tmp/smoke/bin/sobres serve --help > /dev/null
+          /tmp/smoke/bin/python -c "import sobres; print(sobres.__version__)"
+          /tmp/smoke/bin/python -c "import yfinance; assert callable(yfinance.Ticker)"
+
+      - name: The three-command path, in the clean environment
+        # Onboarding is tested end to end: init, doctor, then one data command
+        # served from the recorded fixtures rather than the network.
+        env:
+          SOBRES_CONFIG_FILE: /tmp/smoke-home/config.toml
+          SOBRES_DB_URL: sqlite:////tmp/smoke-home/sobres.db
+          SOBRES_FIXTURE_DIR: ${{ github.workspace }}/tests/fixtures
+        run: |
+          /tmp/smoke/bin/sobres init --non-interactive --offline
+          /tmp/smoke/bin/sobres doctor --offline
+          /tmp/smoke/bin/sobres data prices AAPL MSFT --start 2020-01-01 --end 2020-03-31 --format csv \
+            | head -5
+          /tmp/smoke/bin/sobres data prices AAPL MSFT --start 2020-01-01 --end 2020-03-31 --format json \
+            | /tmp/smoke/bin/python -c "import json,sys; d=json.load(sys.stdin); assert d['columns']==['AAPL','MSFT'], d['columns']; print(len(d['rows']), 'rows')"
+
+      - name: Confirm the sdist builds a wheel
+        run: |
+          python -m venv /tmp/sdist
+          /tmp/sdist/bin/pip install --upgrade pip build
+          /tmp/sdist/bin/pip wheel --no-deps -w /tmp/sdist-out dist/*.tar.gz
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  docker:
+    name: Container image (quickstart, size budget)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-buildx-action@v3
+      - name: Build the image from this checkout
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: sobres:ci
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: The CLI is the entrypoint, as a non-root user
+        run: |
+          docker run --rm sobres:ci --help | grep -q "Usage: sobres"
+          docker run --rm sobres:ci --version
+          test "$(docker run --rm --entrypoint id sobres:ci -u)" = "1000"
+          test "$(docker run --rm --entrypoint id sobres:ci -g)" = "1000"
+
+      - name: A missing data volume fails loudly
+        run: |
+          mkdir -p /tmp/ro && chmod 555 /tmp/ro
+          set +e
+          out=$(docker run --rm -v /tmp/ro:/data:ro sobres:ci db info 2>&1)
+          code=$?
+          set -e
+          echo "$out"
+          test "$code" -ne 0
+          echo "$out" | grep -q "/data"
+
+      - name: The documented quickstart, end to end
+        run: |
+          docker volume create sobres-ci
+          docker run -d --name sobres-ci -p 8787:8787 -v sobres-ci:/data sobres:ci serve --host 0.0.0.0
+          for _ in $(seq 1 30); do
+            if curl -fsS http://127.0.0.1:8787/api/v1/health > /tmp/health.json; then break; fi
+            sleep 1
+          done
+          cat /tmp/health.json
+          python3 -c "import json; d=json.load(open('/tmp/health.json')); assert d['app']=='sobres' and d['ready'], d"
+          curl -fsS http://127.0.0.1:8787/ | grep -qi "<div id=\"root\""
+          docker exec sobres-ci sobres deploy health --port 8787
+          docker logs sobres-ci 2>&1 | grep -q "token"
+          # A one-off command shares the same volume, then the container is replaced and data survives.
+          docker run --rm -v sobres-ci:/data sobres:ci portfolio save core --tickers AAPL MSFT --weights 0.6 0.4
+          docker stop -t 10 sobres-ci && docker rm sobres-ci
+          docker run --rm -v sobres-ci:/data sobres:ci portfolio list --format json | grep -q '"core"'
+          docker run --rm -v sobres-ci:/data sobres:ci doctor --offline
+
+      - name: The compressed image is under the 500 MB budget
+        run: |
+          size=$(docker save sobres:ci | gzip | wc -c)
+          echo "compressed image: $((size / 1024 / 1024)) MB"
+          test "$size" -lt $((500 * 1024 * 1024))
+
+      - name: The runtime stage carries no Node or build toolchain
+        run: |
+          ! docker run --rm --entrypoint sh sobres:ci -c "command -v node || command -v npm || command -v gcc"
+
+  security:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[dev]" pip-audit
+
+      - name: Resolve the dependency tree
+        # Audit what this project actually pulls in, across every extra --
+        # `--exclude-editable` drops the local project (which is not on any
+        # index and so can never be audited), and `pip freeze` already omits
+        # pip/setuptools/wheel, whose advisories belong to the runner image
+        # rather than to this codebase. Auditing the ambient environment
+        # instead would fail on whatever pip version the runner happens to ship.
+        run: pip freeze --exclude-editable > requirements-audit.txt
+
+      - name: pip-audit
+        # A known vulnerability blocks merge and release by design. To ship past
+        # an unfixable transitive advisory, add `--ignore-vuln <ID>` here with a
+        # comment saying why -- see docs/RELEASING.md.
+        run: pip-audit --strict --progress-spinner=off -r requirements-audit.txt
+
+  # Single required status check. Branch protection points at this one job, so
+  # the matrix above can grow or shrink without editing protection rules.
+  all-green:
+    name: All checks passed
+    if: always()
+    needs: [lint, typecheck, test, frontend, build, docker, security]
+    runs-on: ubuntu-latest
+    steps:
+      # `if: always()` means this job runs even when a dependency failed, so it
+      # must inspect the results itself rather than rely on job ordering.
+      # Anything that is not `success` -- failed, cancelled, or skipped -- is a
+      # red gate; a skipped required job must never read as passing.
+      #
+      # The condition lives on the step, not in shell. A multi-line `${{ }}`
+      # interpolated into an `if` statement expands to a continuation line
+      # starting with `||`, which bash rejects as a syntax error -- so the gate
+      # would fail even when every job passed.
+      - name: Fail if any dependency did not succeed
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
+        run: |
+          echo "::error::Required jobs did not all succeed: ${{ join(needs.*.result, ', ') }}"
+          exit 1
+
+      - name: All required jobs succeeded
+        run: |
+          echo "Results: ${{ join(needs.*.result, ', ') }}"