shotgate 0.2.0__tar.gz → 0.2.2__tar.gz

shotgate-0.2.2/.github/workflows/dockerhub-mirror.yml

@@ -0,0 +1,91 @@
+name: dockerhub-mirror
+
+# Mirror an already-published GHCR image set to Docker Hub, then sync this repo's
+# README and tagline onto the Docker Hub repository page so the listing matches the
+# source. GHCR stays the canonical registry; Docker Hub is a convenience mirror for
+# discovery and the familiar `docker pull`. Runs on release (via workflow_call from
+# release.yml) and on demand (workflow_dispatch) to re-mirror or back-fill any version.
+#
+# Credentials live in the `dockerhub` environment: DOCKERHUB_USERNAME and
+# DOCKERHUB_TOKEN (a Docker Hub access token), and optionally DOCKERHUB_NAMESPACE
+# to push under a Hub organization instead of the username. Absent credentials
+# (a fork), the mirror step is skipped rather than failing.
+#
+# The README sync uses peter-evans/dockerhub-description, which drives the Docker
+# Hub HTTP API. That API accepts a personal access token only if it is scoped
+# read/write/delete; if DOCKERHUB_TOKEN is scoped narrower, set
+# DOCKERHUB_DESCRIPTION_PASSWORD in the `dockerhub` environment (the account
+# password or a read/write/delete token) and it is used in preference. The sync
+# step is non-fatal (`continue-on-error`): a description failure never blocks the
+# image mirror or the release.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to mirror from GHCR to Docker Hub (e.g. 0.2.1)"
+        required: true
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: read
+
+jobs:
+  mirror:
+    name: mirror GHCR -> Docker Hub
+    runs-on: ubuntu-latest
+    environment: dockerhub
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+      DOCKERHUB_NAMESPACE: ${{ secrets.DOCKERHUB_NAMESPACE }}
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Compute Docker Hub repository
+        id: hub
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        run: |
+          # Namespace defaults to the Hub username; DOCKERHUB_NAMESPACE overrides
+          # it to push under a Hub organization. Same rule as the mirror step.
+          NS="${DOCKERHUB_NAMESPACE:-$DOCKERHUB_USERNAME}"
+          echo "repository=${NS,,}/shotgate" >> "$GITHUB_OUTPUT"
+
+      - name: Mirror the version, latest, and -ibm tags
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACTOR: ${{ github.actor }}
+          REPO: ${{ github.repository }}
+          VERSION: ${{ inputs.version }}
+          HUB_REPO: ${{ steps.hub.outputs.repository }}
+        run: |
+          V="${VERSION#v}"                      # tolerate a leading 'v'
+          GHCR="ghcr.io/${REPO,,}"
+          DH="docker.io/${HUB_REPO}"
+          echo "$GH_TOKEN" | podman login ghcr.io -u "$ACTOR" --password-stdin
+          echo "$DOCKERHUB_TOKEN" | podman login docker.io -u "$DOCKERHUB_USERNAME" --password-stdin
+          for tag in "$V" latest "${V}-ibm" latest-ibm; do
+            podman pull "${GHCR}:${tag}"
+            podman tag "${GHCR}:${tag}" "${DH}:${tag}"
+            podman push "${DH}:${tag}"
+          done
+          echo "Mirrored ${GHCR}:{${V},latest,${V}-ibm,latest-ibm} -> ${DH}"
+
+      # Keep the Docker Hub repository page in sync with the source: the repo
+      # README becomes the full description, the project tagline the short one.
+      - name: Sync Docker Hub README and short description
+        if: ${{ env.DOCKERHUB_USERNAME != '' && env.DOCKERHUB_TOKEN != '' }}
+        continue-on-error: true
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_DESCRIPTION_PASSWORD || secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ steps.hub.outputs.repository }}
+          short-description: "Container-native CI/CD quality gates for quantum circuits"
+          readme-filepath: ./README.md

{shotgate-0.2.0 → shotgate-0.2.2}/.github/workflows/hardware-validation.yml

@@ -11,9 +11,9 @@ on:
   workflow_dispatch:
     inputs:
       device:
-        description: "IBM device to pin (empty = least_busy)"
+        description: "IBM device to pin (empty = least_busy, the portable default)"
         required: false
-        default: "ibm_fez"
+        default: ""
       shots:
         description: "Shots per job"
         required: false
@@ -73,6 +73,30 @@ jobs:
               exit "$fail"
             '
 
+      - name: Oracle-coverage diagnostic (non-gating, measures chi_square on QPU)
+        env:
+          SHOTGATE_IBM_TOKEN: ${{ secrets.SHOTGATE_IBM_TOKEN }}
+          DEVICE: ${{ inputs.device }}
+          SHOTS: ${{ inputs.shots }}
+          REQUESTED_VERSION: ${{ inputs.version }}
+        run: |
+          # Runs all five oracles on one Bell circuit so chi_square has a hardware
+          # data point. chi_square is EXPECTED to fail under device noise, so this
+          # step never fails the job (|| true); the JSON report carries the number.
+          podman run --rm \
+            -v "$PWD:/work:ro" -v "$PWD/reports:/reports" \
+            -e SHOTGATE_IBM_TOKEN -e DEVICE -e SHOTS -e REQUESTED_VERSION \
+            docker.io/library/python:3.12-slim bash -euc '
+              SPEC="shotgate[ibm]"
+              [ -n "$REQUESTED_VERSION" ] && SPEC="shotgate[ibm]==$REQUESTED_VERSION"
+              pip install -q --no-cache-dir "$SPEC"
+              wf=bell-state-hardware-oracle-coverage
+              cp -r "/work/examples/${wf}" "/tmp/${wf}" && cd "/tmp/${wf}"
+              python /work/.github/scripts/pin-device.py workflow.yaml "$DEVICE"
+              shotgate run workflow.yaml --shots "$SHOTS" \
+                --json "/reports/${wf}.json" --markdown "/reports/${wf}.md" || true
+            ' || true
+
       - name: Publish step summary
         if: always()
         run: |

{shotgate-0.2.0 → shotgate-0.2.2}/.github/workflows/pypi-smoke.yml

@@ -40,7 +40,16 @@ jobs:
             docker.io/library/python:3.12-slim bash -euc '
               SPEC="shotgate[aer]"
               [ -n "$REQUESTED_VERSION" ] && SPEC="shotgate[aer]==$REQUESTED_VERSION"
-              pip install -q --no-cache-dir "$SPEC" pytest
+              # A freshly released version can lag for several minutes in the PyPI
+              # /simple/ index that pip reads, even after the files are live and the
+              # per-release JSON shows them (observed ~10 min on 2026-06-11). Retry
+              # generously so dispatching right after a release tolerates the lag.
+              for attempt in $(seq 1 20); do
+                pip install -q --no-cache-dir "$SPEC" pytest && break
+                echo "install attempt ${attempt}/20 failed (index may be propagating); retrying in 45s" >&2
+                sleep 45
+              done
+              pip show shotgate >/dev/null  # fail the step if all attempts failed
               echo "--- installed:"
               pip show shotgate | sed -n "1,2p"
               echo "--- CLI gate (exit 0 expected):"

{shotgate-0.2.0 → shotgate-0.2.2}/.github/workflows/release.yml

@@ -98,6 +98,17 @@ jobs:
           podman push "${IMG}:${VERSION}-ibm"
           podman push "${IMG}:latest-ibm"
 
+  # Mirror the just-published GHCR images to Docker Hub (optional convenience
+  # registry). Delegated to the reusable dockerhub-mirror workflow, which is also
+  # dispatchable on its own to re-mirror any version. Skipped automatically when
+  # the dockerhub environment has no credentials.
+  mirror-dockerhub:
+    needs: publish-image
+    uses: ./.github/workflows/dockerhub-mirror.yml
+    with:
+      version: ${{ github.ref_name }}
+    secrets: inherit
+
   publish-pypi:
     name: publish to PyPI (trusted publishing)
     runs-on: ubuntu-latest
@@ -134,8 +145,38 @@ jobs:
         with:
           name: dist
           path: dist
+      - name: Compose install instructions
+        id: notes
+        run: |
+          V="${GITHUB_REF_NAME#v}"
+          {
+            echo "## Install ${GITHUB_REF_NAME}"
+            echo
+            echo "The package is on **PyPI** and the image on the **GitHub Container Registry (GHCR)** for convenience (the usual one-liners below). If you would rather not use a package index at all, the wheel attached to this release and the GHCR image are both pullable straight from GitHub, no extra account needed."
+            echo
+            echo "**Python package** (PyPI, or the attached wheel):"
+            echo '```bash'
+            echo "pip install 'shotgate[aer]==${V}'"
+            echo "# or straight from this release, no index:"
+            echo "pip install https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/shotgate-${V}-py3-none-any.whl"
+            echo '```'
+            echo
+            echo "**Container** (GHCR, canonical; add the \`-ibm\` tag suffix for the QPU-capable variant):"
+            echo '```bash'
+            echo "podman pull ghcr.io/${GITHUB_REPOSITORY}:${V}"
+            echo "podman run --rm -v \"\$PWD:/work:Z\" -w /work ghcr.io/${GITHUB_REPOSITORY}:${V} run examples/bell-state/workflow.yaml"
+            echo "# also mirrored to Docker Hub:  docker.io/${GITHUB_REPOSITORY}:${V}"
+            echo '```'
+            echo
+            echo "---"
+          } > release-notes.md
+        env:
+          GITHUB_REPOSITORY: ${{ github.repository }}
+
       - name: Create release
         uses: softprops/action-gh-release@v3
         with:
           files: dist/*
+          body_path: release-notes.md
+          append_body: true
           generate_release_notes: true

{shotgate-0.2.0 → shotgate-0.2.2}/CHANGELOG.md

@@ -6,7 +6,57 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
-*Nothing yet.*
+## [0.2.2] - 2026-06-11
+
+### Added
+
+- **Three Architecture Decision Records.** ADR-0004 (rename `qforge` to `shotgate`,
+  including the breaking `apiVersion` change), ADR-0005 (license MIT to
+  AGPL-3.0-or-later to Apache-2.0, and the DCO inbound policy), and ADR-0006
+  (`chi_square` simulator-only, noise-aware hardware thresholds), completing the
+  ADR series against the GOVERNANCE.md criteria.
+- **Docker Hub repository page sync.** After mirroring images, the `dockerhub-mirror`
+  workflow now pushes the repository README and the project tagline to the Docker Hub
+  repository description, so the Hub listing tracks the source. The step is non-fatal:
+  a description-API failure never blocks the image mirror or the release.
+
+### Changed
+
+- **Docker Hub mirroring is a reusable, dispatchable workflow.** The mirror moved from an
+  inline release job to `dockerhub-mirror.yml` (`workflow_call` from the release plus
+  `workflow_dispatch` to back-fill any version), with credentials read from the
+  `dockerhub` environment (`DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`, optional
+  `DOCKERHUB_NAMESPACE`) instead of repository secrets.
+- **Reporter copy uses ASCII separators.** The Markdown summary title format is now
+  ``## shotgate: `name` (status)``, the no-assertion row prints `n/a`, and the plain
+  console fallback separates label and message with a colon; previously all three used
+  an em-dash. JUnit and JSON payloads are unchanged.
+
+## [0.2.1] - 2026-06-11
+
+### Added
+
+- **Full oracle coverage on hardware.** A non-gating diagnostic example,
+  `bell-state-hardware-oracle-coverage`, runs all five oracles on one Bell circuit so
+  `chi_square` also has a real-QPU data point. Measured on `ibm_fez`: the four
+  distance/structural oracles passed while `chi_square` returned p-value 0.0000
+  (statistic 1.5e17, dof 3), confirming why it is simulator-only. Mechanism and numbers
+  in `docs/hardware-validation.md` section 9.
+- **GitHub-only install path in release notes.** Each release now documents installing the
+  attached wheel and pulling the GHCR image directly, so neither PyPI nor Docker Hub is
+  required to consume a release.
+- **Optional Docker Hub mirror** in the release pipeline. When the `DOCKERHUB_USERNAME` and
+  `DOCKERHUB_TOKEN` repository secrets are present, released images are mirrored to Docker
+  Hub alongside the canonical GHCR images; absent the secrets the step is skipped and the
+  release is unaffected.
+
+### Changed
+
+- **Portable device selection.** A pinned `ibm` device that the account or instance cannot
+  reach now raises a clear error listing the reachable real devices and pointing at the
+  `least_busy` default, instead of an opaque Qiskit lookup failure. The
+  `hardware-validation` workflow's device input now defaults to empty (`least_busy`) rather
+  than a pinned `ibm_fez`.
 
 ## [0.2.0] - 2026-06-11
 
@@ -76,7 +126,7 @@ All notable changes to this project are documented here. The format is based on
   moved to the new name. The canonical home is `github.com/coldqubit/shotgate` and the
   published image is `ghcr.io/coldqubit/shotgate`.
 - **Pull-first usage.** Documentation now leads with `podman run
-  ghcr.io/coldqubit/shotgate …`; building from source is the contributor fallback.
+  ghcr.io/coldqubit/shotgate ...`; building from source is the contributor fallback.
 - **Honest extras.** `braket` and `mitigation` are marked *planned* and removed from the
   installable `all` extra, since no Braket backend or Mitiq integration ships yet.
   `--backend braket` now fails fast at schema validation with a clear message.
@@ -97,7 +147,7 @@ All notable changes to this project are documented here. The format is based on
 - **Hardened IBM/QPU backend**: robust counts extraction from named classical registers
   (with a clear error on unexpected result shapes), corrected Runtime channel default,
   a token-gated smoke test, and an `[ibm]`-baked image variant (build arg
-  `SHOTGATE_EXTRAS="aer,ibm"`, published as the `:…-ibm` image tag).
+  `SHOTGATE_EXTRAS="aer,ibm"`, published as the `:...-ibm` image tag).
 - **Noise-tolerant example** (`examples/bell-state-hardware/`) with relaxed thresholds
   for real-device runs, plus a documented simulator-vs-QPU threshold split.
 - **`docs/hardware-validation.md`**: a step-by-step plan and acceptance matrix for
@@ -143,7 +193,9 @@ All notable changes to this project are documented here. The format is based on
   (with the math), getting-started guide, and ADRs.
 - **Examples**: Bell state, 3-qubit GHZ, and 2-qubit Grover workflows.
 
-[Unreleased]: https://github.com/coldqubit/shotgate/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/coldqubit/shotgate/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/coldqubit/shotgate/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/coldqubit/shotgate/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/coldqubit/shotgate/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/coldqubit/shotgate/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/coldqubit/shotgate/releases/tag/v0.1.0

{shotgate-0.2.0 → shotgate-0.2.2}/CONTRIBUTING.md

@@ -7,11 +7,11 @@ favors small, well-tested, well-reasoned changes.
 
 - Be kind; follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 - Discuss non-trivial changes in an issue first (especially new assertion oracles or
-  backends — they have design implications).
+  backends, which have design implications).
 - Keep the **validation core dependency-free** (standard library + pydantic). Quantum
   SDKs are optional extras, imported lazily inside backends only.
 
-## Development workflow (containers only — no host installs)
+## Development workflow (containers only, no host installs)
 
 Everything runs through Podman via the `Makefile`:
 

{shotgate-0.2.0 → shotgate-0.2.2}/Containerfile

@@ -1,4 +1,4 @@
-# shotgate runtime image — built and run with Podman (rootless-friendly).
+# shotgate runtime image, built and run with Podman (rootless-friendly).
 #
 # Multi-stage:
 #   builder  -> installs shotgate + the Aer simulator into an isolated venv

{shotgate-0.2.0 → shotgate-0.2.2}/Makefile

@@ -1,4 +1,4 @@
-# shotgate — Podman/QEMU task runner.
+# shotgate: Podman/QEMU task runner.
 #
 # Everything runs in containers or VMs; nothing is installed on the host.
 # Override any variable on the command line, e.g.  make run WORKFLOW=examples/ghz-state/workflow.yaml
@@ -14,7 +14,7 @@ MOUNT       := -v "$(CURDIR):/work:Z" -w /work
 RUN         := $(PODMAN) run --rm $(MOUNT)
 
 # Map the invoking host user through the container's user namespace so that
-# report files written to the bind mount are owned by you — while the image
+# report files written to the bind mount are owned by you, while the image
 # keeps its non-root default user. The standard Podman idiom for this case.
 USERMAP     := --userns=keep-id --user $(shell id -u):$(shell id -g)
 

{shotgate-0.2.0 → shotgate-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shotgate
-Version: 0.2.0
+Version: 0.2.2
 Summary: Container-native CI/CD quality gates for quantum circuits: statistically validate probabilistic output across simulators and QPUs.
 Project-URL: Homepage, https://github.com/coldqubit/shotgate
 Project-URL: Documentation, https://github.com/coldqubit/shotgate/tree/main/docs
@@ -138,7 +138,7 @@ $ shotgate run examples/bell-state/workflow.yaml
 The same run drops into a pipeline through the Markdown reporter (`--markdown`), rendered
 as a step summary or a PR comment:
 
-> ## shotgate: `bell-state` — ✅ passed
+> ## shotgate: `bell-state` (✅ passed)
 >
 > - Jobs: **1**, failed: **0**
 > - Assertions: **5**, failed: **0**
@@ -180,6 +180,10 @@ podman run --rm -e SHOTGATE_IBM_TOKEN \
   run examples/bell-state-hardware/workflow.yaml --backend ibm
 ```
 
+The same images are mirrored to Docker Hub if you prefer it: swap the registry prefix for
+`docker.io/coldqubit/shotgate` (tags `latest`, `latest-ibm`, and each version). GHCR is the
+canonical registry; the Docker Hub copy is a convenience mirror.
+
 ### Path B: pip (CLI and pytest plugin)
 
 Install the package with the backend extra you need (`aer` for the local simulator, `ibm` for

{shotgate-0.2.0 → shotgate-0.2.2}/README.md

@@ -91,7 +91,7 @@ $ shotgate run examples/bell-state/workflow.yaml
 The same run drops into a pipeline through the Markdown reporter (`--markdown`), rendered
 as a step summary or a PR comment:
 
-> ## shotgate: `bell-state` — ✅ passed
+> ## shotgate: `bell-state` (✅ passed)
 >
 > - Jobs: **1**, failed: **0**
 > - Assertions: **5**, failed: **0**
@@ -133,6 +133,10 @@ podman run --rm -e SHOTGATE_IBM_TOKEN \
   run examples/bell-state-hardware/workflow.yaml --backend ibm
 ```
 
+The same images are mirrored to Docker Hub if you prefer it: swap the registry prefix for
+`docker.io/coldqubit/shotgate` (tags `latest`, `latest-ibm`, and each version). GHCR is the
+canonical registry; the Docker Hub copy is a convenience mirror.
+
 ### Path B: pip (CLI and pytest plugin)
 
 Install the package with the backend extra you need (`aer` for the local simulator, `ibm` for

{shotgate-0.2.0 → shotgate-0.2.2}/SECURITY.md

@@ -15,7 +15,7 @@ acknowledge within 72 hours and to provide a remediation timeline after triage.
 
 ## Security model (what to attack / what we defend)
 
-- **Untrusted circuits.** Circuits are OpenQASM parsed by qiskit's QASM reader — not
+- **Untrusted circuits.** Circuits are OpenQASM parsed by qiskit's QASM reader, not
   `eval`'d Python. For circuits from untrusted sources, use the **VM isolation tier**
   (`infra/qemu`), which runs the workflow in an ephemeral KVM micro-VM.
 - **Secrets.** Provider tokens are read from environment variables / container `-e`

{shotgate-0.2.0 → shotgate-0.2.2}/docs/README.md

@@ -7,12 +7,12 @@
 | [Pipeline Schema](pipeline.md) | How shotgate gates a CI/CD pipeline; stage contract; exit codes. |
 | [Workflow Specification](workflow-spec.md) | The `shotgate.dev/v1alpha1` YAML schema, field by field. |
 | [Assertion Catalog](assertions.md) | The statistical oracles, with the math and threshold guidance. |
-| [Hardware Validation Plan](hardware-validation.md) | v0.2 runbook to validate the gates on a real IBM QPU. |
+| [Hardware Validation Plan](hardware-validation.md) | v0.2 milestone: runbook and measured `ibm_fez` baseline (2026-06-11). |
 | [Motivation](motivation.md) | The market/community gap shotgate fills, with sources. |
 | [ADRs](adr/) | Architecture Decision Records and their rationale. |
 | [Diagrams](diagrams/) | Mermaid sources for the architecture and pipeline diagrams. |
 
 Infrastructure docs live next to the code they describe:
 
-- [Terraform module](../infra/terraform/README.md) — quantum workflow as code.
-- [KVM/QEMU runner](../infra/qemu/README.md) — ephemeral VM isolation tier.
+- [Terraform module](../infra/terraform/README.md): quantum workflow as code.
+- [KVM/QEMU runner](../infra/qemu/README.md): ephemeral VM isolation tier.

{shotgate-0.2.0 → shotgate-0.2.2}/docs/adr/0001-record-architecture-decisions.md

@@ -6,8 +6,8 @@
 ## Context
 
 shotgate sits at an immature intersection (quantum × DevOps) where the "right" design
-is not yet settled by convention. Decisions — why statistical oracles, why containers,
-why a Terraform module instead of a provider — need to be legible to contributors and
+is not yet settled by convention. Decisions (why statistical oracles, why containers,
+why a Terraform module instead of a provider) need to be legible to contributors and
 to our future selves.
 
 ## Decision

{shotgate-0.2.0 → shotgate-0.2.2}/docs/adr/0002-statistical-validation-core.md

@@ -7,10 +7,10 @@
 
 Quantum programs are probabilistic; exact-equality assertions are either flaky or
 vacuous. The academic literature (χ²-as-oracle, QUTest, QuCheck, QUT) establishes the
-correct techniques — total variation distance, Hellinger fidelity, chi-square
-goodness-of-fit — but they live in research prototypes, not in production CI tooling.
+correct techniques (total variation distance, Hellinger fidelity, chi-square
+goodness-of-fit), but they live in research prototypes, not in production CI tooling.
 Meanwhile DevOps writers repeatedly note that quantum CI "lacks robust test
-frameworks" and needs "specialized validation… in CI/CD pipelines".
+frameworks" and needs "specialized validation... in CI/CD pipelines".
 
 We must also decide the dependency footprint. Pulling SciPy (for `chi2.sf`) and numpy
 into the core would make the metrics layer heavy and couple it to a scientific stack.

shotgate-0.2.2/docs/adr/0004-rename-qforge-to-shotgate.md

@@ -0,0 +1,35 @@
+# ADR-0004: Rename qforge to shotgate (and the workflow apiVersion with it)
+
+- **Status:** Accepted
+- **Date:** 2026-06-01
+
+## Context
+
+The project started on 2026-06-01 under the name `qforge`. Before any release was
+tagged, two problems surfaced: the name was already taken on the package indexes
+(PyPI and crates.io), and it raised a trademark concern on the VS Code marketplace.
+The name is load-bearing in more places than the repository title: the Python
+package, the command-line interface (CLI) program, the container image path, the
+environment variables, and the workflow schema's `apiVersion` literal
+(`qforge.dev/v1alpha1`) all embed it.
+
+## Decision
+
+Rename the project to **shotgate** everywhere the old name appeared: package
+`src/shotgate`, CLI program `shotgate`, image `ghcr.io/coldqubit/shotgate`,
+environment variable prefix `SHOTGATE_*`, and the workflow schema pin
+`apiVersion: shotgate.dev/v1alpha1`. The schema pin is a pydantic `Literal`, so a
+workflow declaring the old `qforge.dev/v1alpha1` fails schema validation rather
+than being silently accepted.
+
+## Consequences
+
+- **+** The name is unique on PyPI and the container registries, so the package and
+  image are installable under their own name with no squatting or trademark risk.
+- **+** It describes the product (gating on measurement shots) instead of a generic
+  "forge" metaphor.
+- **−** The `apiVersion` change is breaking for any pre-rename workflow file. The
+  impact was zero in practice: the rename landed on 2026-06-01 and the first tagged
+  release (`v0.1.0`) followed on 2026-06-10, so no published package, image, or tag
+  ever carried the old name and no external consumer existed to break.
+- The old name survives only in git history and in the `CHANGELOG.md` v0.1.0 notes.

shotgate-0.2.2/docs/adr/0005-license-apache-2-0.md

@@ -0,0 +1,48 @@
+# ADR-0005: License is Apache-2.0 (after MIT and an AGPL interlude)
+
+- **Status:** Accepted
+- **Date:** 2026-06-08
+
+## Context
+
+The project's license changed twice before the first release settled it:
+
+1. **MIT** at inception (2026-06-01).
+2. **AGPL-3.0-or-later** later the same day, chosen for the network copyleft:
+   distributing the tool, or running a modified version as a hosted service, would
+   have required releasing source.
+3. **Apache-2.0** on 2026-06-08, two days before the first tagged release.
+
+The week under AGPL exposed a conflict with the adoption model. shotgate's target
+user is a corporate continuous integration (CI) pipeline, and the quantum ecosystem
+it builds on (Qiskit, Qiskit Aer, Cirq, Mitiq) is Apache-2.0 licensed; a
+network-copyleft gate inside that stack invites legal review friction that a CI
+utility cannot justify, and the "hosted modified service" trigger is ambiguous for a
+tool whose whole purpose is to run inside other people's pipelines.
+
+Relicensing was legally clean at that date: every line of source had a single
+copyright holder (the maintainer), since the only third-party commits were
+Dependabot version-range bumps and none had landed before the relicense commit.
+
+## Decision
+
+License the project **Apache-2.0**: verbatim license text in `LICENSE`, the
+two-line SPDX header (`Apache-2.0`, `Copyright (C) 2026 coldqubit`) in all `src/`
+files (17 files at the time), the `Apache-2.0` expression and classifier in
+`pyproject.toml`, and the OCI license label in the `Containerfile`. Inbound
+contributions are accepted under a Developer Certificate of Origin (DCO) sign-off
+carrying the same Apache-2.0 terms (Apache-2.0 section 5), with no separate
+contributor license agreement.
+
+## Consequences
+
+- **+** Permissive adoption: use, modification, and redistribution for any purpose,
+  including commercial and closed-source, retaining the license and attribution
+  notices (Apache-2.0 sections 4(a) through 4(d)).
+- **+** An explicit patent grant (section 3), which MIT lacked.
+- **+** License-compatible with the Apache-2.0 quantum SDK stack it imports.
+- **−** The AGPL network-copyleft promise is removed, not replaced: a vendor can
+  ship a modified closed-source shotgate as a service.
+- **−** Practically irreversible: once external DCO-signed contributions land,
+  relicensing again would require every contributor's consent. This ADR therefore
+  also fixes the inbound policy (DCO, same license in and out).

shotgate-0.2.2/docs/adr/0006-hardware-oracle-policy.md

@@ -0,0 +1,48 @@
+# ADR-0006: chi_square is simulator-only; hardware gates use distance, fidelity, and structural oracles
+
+- **Status:** Accepted
+- **Date:** 2026-06-11
+
+## Context
+
+The v0.2 milestone ran the example gates on a real quantum processing unit (QPU)
+for the first time (`ibm_fez`, 156-qubit Heron r2, 4096 shots per job). Two facts
+came out of those runs:
+
+1. Simulator-tight thresholds (total variation distance (TVD) ≤ 0.03, Hellinger
+   fidelity ≥ 0.99, leakage ≤ 0.005) fail on a healthy device: the measured Bell
+   TVD was 0.1284 and the GHZ-3 TVD 0.1536.
+2. `chi_square` fails on hardware for a mechanical reason, not a tuning one. The
+   non-gating diagnostic Bell job (`d8l592rqv2lc738621eg`) returned statistic
+   1.5e17, dof 3, p-value 0.0000, while the four distance/structural oracles passed
+   on the same counts (TVD 0.1350, fidelity 0.8650, leakage 0.1350, P(`00`) 0.4343).
+   The ideal expected distribution `{00: 0.5, 11: 0.5}` assigns probability 0 to
+   the error states `01`/`10`; the implementation floors expected counts at
+   `_MIN_EXPECTED = 1e-12` to keep the statistic finite, so each of the 553 leaked
+   shots contributes on the order of `observed^2 / 1e-12`. Against an ideal support,
+   any device leakage forces rejection regardless of thresholds.
+
+## Decision
+
+1. **Hardware gates use the distance, fidelity, marginal, and structural oracles**
+   (`distribution_tvd`, `hellinger_fidelity`, `state_probability`,
+   `allowed_states`) with noise-aware thresholds (Bell: TVD ≤ 0.15, fidelity
+   ≥ 0.85, leakage ≤ 0.15; full table in `docs/hardware-validation.md` section 4),
+   encoded in the `examples/*-hardware` workflows.
+2. **`chi_square` stays simulator-only** until a gate can declare a noise-aware
+   expected distribution (a device error model with nonzero mass on the error
+   states), which is out of scope for v0.2.
+3. A **non-gating oracle-coverage diagnostic**
+   (`examples/bell-state-hardware-oracle-coverage`) keeps measuring all five
+   oracles on hardware so the exclusion stays evidence-based run over run.
+
+## Consequences
+
+- **+** The hardware gates pass a healthy device with measured margins of 0.0216
+  (Bell TVD, the tightest) to 0.1357 (Grover P(`11`)) while still bounding leakage
+  and fidelity, so they catch a broken circuit or mis-mapped qubits.
+- **−** The formal hypothesis test is unavailable on hardware, so hardware gating
+  loses the goodness-of-fit (GoF) guarantee and relies on distance bounds instead.
+- Revisit when an error-model expected distribution exists (candidate for the v0.3
+  error-mitigation work); the diagnostic's measurements will show when `chi_square`
+  becomes viable on devices.