From 4a79377480a4fb6fcac1af349ba1cd273a193e19 Mon Sep 17 00:00:00 2001 From: D Thomas <146stat@gmail.com> Date: Sun, 2 Aug 2026 06:39:02 +0000 Subject: [PATCH] chore: establish public project governance --- .github/ISSUE_TEMPLATE/alpha_feedback.yml | 68 ++++++++++++ .github/ISSUE_TEMPLATE/bug_report.yml | 51 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 2 + .github/ISSUE_TEMPLATE/feature_request.yml | 33 ++++++ .github/pull_request_template.md | 23 +++++ .github/workflows/ci.yml | 6 +- .github/workflows/docs.yml | 6 +- .github/workflows/publish-testpypi.yml | 8 +- ALPHA_TESTING.md | 114 +++++++++++++++++++++ CODE_OF_CONDUCT.md | 36 +++++++ CONTRIBUTING.md | 77 ++++++++++++++ SECURITY.md | 65 ++++++++++++ SUPPORT.md | 48 +++++++++ 13 files changed, 527 insertions(+), 10 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/alpha_feedback.yml create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/pull_request_template.md create mode 100644 ALPHA_TESTING.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md create mode 100644 SUPPORT.md diff --git a/.github/ISSUE_TEMPLATE/alpha_feedback.yml b/.github/ISSUE_TEMPLATE/alpha_feedback.yml new file mode 100644 index 0000000..3c84a2f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/alpha_feedback.yml @@ -0,0 +1,68 @@ +name: Alpha evaluation feedback +description: Share structured feedback from the public-alpha evaluation +title: "alpha feedback: " +labels: + - alpha-feedback +body: + - type: input + id: evaluator + attributes: + label: Evaluator perspective + placeholder: Quantum developer, security engineer, researcher, or other + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + placeholder: Windows WSL, Python 3.12 + validations: + required: true + - type: input + id: install_time + attributes: + label: Installation time + placeholder: 8 minutes + validations: + required: true + - type: input + id: verified_time + attributes: + label: Time to first verified chain + placeholder: 12 minutes + validations: + required: true + - type: textarea + id: confusion + attributes: + label: Where did you become confused? + validations: + required: true + - type: textarea + id: skepticism + attributes: + label: Which claim felt least credible? + validations: + required: true + - type: textarea + id: understanding + attributes: + label: Explain the Evidence Graph and trust boundary + validations: + required: true + - type: textarea + id: workflow + attributes: + label: What real workflow would you test next? + validations: + required: true + - type: dropdown + id: continue + attributes: + label: Would you continue evaluating QuantumD? + options: + - "Yes" + - "Maybe" + - "No" + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..dd56dd8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,51 @@ +name: Bug report +description: Report a reproducible QuantumD defect +title: "bug: " +labels: + - bug +body: + - type: markdown + attributes: + value: | + Do not include credentials, private keys, confidential evidence, or vulnerability details. Security reports must follow SECURITY.md. + - type: input + id: version + attributes: + label: QuantumD version + placeholder: 0.7.4a0 + validations: + required: true + - type: input + id: environment + attributes: + label: Environment + description: Operating system and Python version + placeholder: Ubuntu 24.04, Python 3.12 + validations: + required: true + - type: textarea + id: command + attributes: + label: Command or workflow + description: Provide the exact sanitized command + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: actual + attributes: + label: Actual behavior + validations: + required: true + - type: textarea + id: reproduction + attributes: + label: Minimal reproduction + description: Include sanitized steps and logs + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..8005e32 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,2 @@ +blank_issues_enabled: false +contact_links: [] diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..1a12792 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,33 @@ +name: Feature request +description: Propose a focused QuantumD capability +title: "feature: " +labels: + - enhancement +body: + - type: textarea + id: problem + attributes: + label: Problem + description: What execution-integrity or verification problem exists? + validations: + required: true + - type: textarea + id: workflow + attributes: + label: Current workflow + description: How is the problem handled today? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: Proposed behavior + validations: + required: true + - type: textarea + id: trust + attributes: + label: Trust-boundary impact + description: What identities, evidence, networks, approvals, or hardware are involved? + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0b8e106 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,23 @@ +## Summary + +Describe the focused change. + +## Trust-boundary impact + +- [ ] No trust-boundary change +- [ ] Trust-boundary change is explained below +- [ ] Fail-closed behavior is preserved +- [ ] No new hardware or network action is introduced unexpectedly + +## Validation + +- [ ] Tests added or updated +- [ ] `python -m pytest -q` passes +- [ ] Documentation builds with `mkdocs build --strict` +- [ ] `bash scripts/public_alpha_acceptance.sh` passes +- [ ] No credentials, private keys, or generated identities are included +- [ ] Third-party GitHub Actions are pinned to commit SHAs + +## Evidence + +Include relevant sanitized output and explain any new or changed evidence fields. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b9596db..8e3e697 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -23,10 +23,10 @@ jobs: steps: - name: Check out repository - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Python 3.12 - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 with: python-version: "3.12" cache: pip @@ -93,7 +93,7 @@ jobs: - name: Public alpha wheel quickstart acceptance run: bash scripts/public_alpha_acceptance.sh - name: Upload validated distributions - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: quantumd-distributions-${{ github.sha }} path: dist/* diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6865ace..7aafc83 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -29,10 +29,10 @@ jobs: steps: - name: Check out repository - uses: actions/checkout@v4 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 with: python-version: "3.12" cache: pip @@ -47,7 +47,7 @@ jobs: run: python -m mkdocs build --strict - name: Upload rendered site - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: quantumd-documentation-site path: site/ diff --git a/.github/workflows/publish-testpypi.yml b/.github/workflows/publish-testpypi.yml index c5d00d6..c1ce45e 100644 --- a/.github/workflows/publish-testpypi.yml +++ b/.github/workflows/publish-testpypi.yml @@ -21,10 +21,10 @@ jobs: steps: - name: Check out release commit - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7 - name: Set up Python 3.12 - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6 with: python-version: "3.12" cache: pip @@ -267,7 +267,7 @@ jobs: echo "Manual release fail-closed check: PASS" - name: Upload verified release distributions - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7 with: name: release-distributions path: dist/* @@ -293,7 +293,7 @@ jobs: steps: - name: Retrieve verified distributions - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8 with: name: release-distributions path: dist/ diff --git a/ALPHA_TESTING.md b/ALPHA_TESTING.md new file mode 100644 index 0000000..57ccafa --- /dev/null +++ b/ALPHA_TESTING.md @@ -0,0 +1,114 @@ +# QuantumD Alpha Evaluation + +QuantumD is recruiting five early technical evaluators to test whether a +stranger can understand, install, run, and assess the execution-integrity +model without founder assistance. + +## Evaluator profiles + +The initial group should include: + +1. a quantum developer +2. a software-supply-chain or security engineer +3. an ML, data, or scientific-computing engineer +4. a technical leader from an audit-exposed environment +5. an educator, researcher, or advanced technical student + +## Evaluation rule + +Complete the installation and quickstart without a live walkthrough. Record +where the documentation creates confusion, skepticism, or unnecessary work. + +## Secure TestPyPI installation + +Create an isolated environment: + +```bash +python3.12 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +``` + +Download the exact QuantumD wheel from TestPyPI without resolving dependencies +from that index: + +```bash +python -m pip download \ + --no-deps \ + --only-binary=:all: \ + --index-url https://test.pypi.org/simple/ \ + quantumd==0.7.4a0 +``` + +Install the downloaded wheel. Its dependencies will resolve from the default +Python Package Index: + +```bash +python -m pip install \ + ./quantumd-0.7.4a0-py3-none-any.whl +``` + +Run the first governed local workflow: + +```bash +quantumd quickstart my-first-quantumd-project +``` + +Inspect the environment and independently verify the evidence: + +```bash +quantumd doctor my-first-quantumd-project + +quantumd verify-chain \ + my-first-quantumd-project \ + --latest +``` + +## Expected security boundary + +The local quickstart should report: + +```text +Trust mode: LOCAL_DEVELOPMENT +Trust scope: LOCAL_SIMULATION_ONLY +Hardware authorization: PROHIBITED +KMS signing used: False +IBM contacted: False +Hardware action: None +``` + +Independent verification should end with: + +```text +[STATUS] COMPLETE EVIDENCE CHAIN VERIFIED +IBM contacted: False +KMS contacted: False +Hardware action: None +``` + +## Feedback questions + +Please report: + +1. How long did installation take? +2. How long until the first verified chain? +3. Where did you become confused? +4. Which claim felt least credible? +5. Could you explain the Evidence Graph in your own words? +6. Could you explain the local trust boundary? +7. What existing tool did QuantumD remind you of? +8. What real workflow would you test next? +9. What evidence would an auditor or reviewer need? +10. Would you continue evaluating QuantumD? Why or why not? + +## What not to share + +Do not include: + +- live credentials +- private keys +- cloud account identifiers +- IBM tokens +- confidential workloads +- sensitive evidence +- regulated or classified information diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..9b7459a --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,36 @@ +# QuantumD Community Code of Conduct + +QuantumD is committed to a professional, respectful, technically rigorous +community. + +## Expected behavior + +Participants should: + +- discuss ideas and evidence rather than attacking people +- give specific, actionable technical feedback +- acknowledge uncertainty and correct mistakes openly +- respect privacy, confidentiality, and security boundaries +- avoid publishing credentials, private evidence, or exploit details +- welcome contributors with different levels of experience +- keep disagreements focused on the work + +## Unacceptable behavior + +The following are not acceptable: + +- harassment, threats, discrimination, or personal attacks +- deliberate humiliation or intimidation +- sexualized or abusive conduct +- disclosure of another person's private information +- knowingly unsafe instructions involving credentials or hardware +- public disclosure of an unpatched vulnerability +- disruption intended to prevent constructive participation + +## Enforcement + +Maintainers may edit or remove content, close discussions, reject +contributions, or restrict participation when behavior threatens the safety, +security, or effectiveness of the project. + +Serious security matters should be reported privately under `SECURITY.md`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6499969 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,77 @@ +# Contributing to QuantumD + +QuantumD welcomes focused contributions that strengthen governed execution, +verification, reproducibility, evidence integrity, documentation, and safe +developer onboarding. + +## Development setup + +Use Python 3.12 for the reference development environment. + +```bash +git clone https://github.com/WindDAnalytics/quantumd.git +cd quantumd + +python3.12 -m venv .venv +source .venv/bin/activate + +python -m pip install --upgrade pip +python -m pip install -e ".[dev]" +``` + +Run the regression suite: + +```bash +python -m compileall -q src tests +python -m pytest -q +``` + +Run the built-wheel public acceptance gate: + +```bash +bash scripts/public_alpha_acceptance.sh +``` + +Build the documentation: + +```bash +python -m pip install -r requirements-docs.txt +mkdocs build --strict +``` + +## Contribution rules + +- Create a focused branch from current `main`. +- Keep each pull request limited to one coherent change. +- Add or update tests for behavioral changes. +- Preserve fail-closed behavior. +- Do not weaken cryptographic, authorization, or evidence bindings. +- Do not introduce network or hardware access into ordinary tests. +- Do not include credentials, tokens, private keys, generated identities, or + confidential evidence. +- Use exact commit SHAs for third-party GitHub Actions. +- Keep local-development trust simulator-only. +- Document new public commands and evidence fields. + +## Security-critical changes + +Changes involving signing, authorization, approvals, submissions, receipts, +evidence verification, trust selection, hardware access, or release workflows +must explain: + +1. the trust boundary before the change +2. the trust boundary after the change +3. the failure behavior +4. the adversarial or regression tests added +5. any new network, identity, or credential dependency + +## Pull-request acceptance + +A pull request should not be considered ready until: + +- tests pass +- documentation builds strictly +- built distributions validate +- the public-alpha wheel gate passes +- the repository remains clean after acceptance +- no sensitive information is introduced diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..df1b3bb --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,65 @@ +# Security Policy + +QuantumD treats execution integrity, evidence authenticity, authorization +binding, and hardware-access boundaries as security-critical behavior. + +## Supported versions + +QuantumD is currently an alpha project. + +| Version | Supported | +| --- | --- | +| 0.7.4a0 | Yes | +| Earlier alpha releases | No | + +Security fixes may require users to upgrade to the newest alpha release. + +## Reporting a vulnerability + +Do not disclose suspected vulnerabilities in a public GitHub issue, +Discussion, pull request, or social post. + +Use GitHub private vulnerability reporting from the repository's **Security** +tab after it is enabled for the public launch. Include: + +- the affected QuantumD version +- the operating system and Python version +- the trust mode involved +- the command or workflow that triggered the issue +- the expected security boundary +- the observed behavior +- a minimal reproduction, when safe +- whether credentials, evidence, or hardware access may have been exposed + +Do not include live tokens, private keys, cloud credentials, IBM credentials, +or confidential evidence in the report. + +## Security-sensitive areas + +Reports are especially important when they involve: + +- unsigned evidence being accepted +- approval replay or substitution +- workload, circuit, job, or result substitution +- mismatched execution identifiers +- invalid evidence chains being reported as verified +- local-development trust authorizing remote hardware +- unexpected IBM, KMS, or network contact +- private-key exposure or unsafe file permissions +- secret disclosure in logs, receipts, reports, or exceptions +- release artifacts that do not match their source or tag + +## Scope boundaries + +Local-development trust is restricted to simulator-only workflows. It is not +a substitute for organization-controlled signing, production authorization, +or remote hardware governance. + +QuantumD alpha software must not be treated as the sole control protecting +safety-critical, classified, regulated, or financially material operations. + +## Disclosure process + +The maintainer will validate the report, determine affected versions, develop +a correction, and coordinate disclosure when appropriate. Public disclosure +should occur only after users have a reasonable opportunity to upgrade. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..a7d6e10 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,48 @@ +# QuantumD Support + +QuantumD is alpha software. Community support is best-effort and does not +include production service-level guarantees. + +## Use GitHub Issues for + +- reproducible software defects +- installation failures +- documentation errors +- unexpected CLI behavior +- evidence-chain verification failures +- simulator quickstart failures + +A useful issue includes: + +- QuantumD version +- operating system +- Python version +- exact command +- expected result +- actual result +- sanitized logs +- minimal reproduction + +## Do not use public issues for + +- vulnerabilities +- credentials or tokens +- private keys +- confidential evidence +- classified or regulated data +- private cloud or IBM account details + +Security concerns must follow `SECURITY.md`. + +## Alpha limitations + +QuantumD currently focuses on: + +- simulator-first governed onboarding +- evidence-bound execution +- independent evidence-chain verification +- controlled IBM planning and execution workflows +- explicit local and KMS trust boundaries + +Alpha interfaces and evidence schemas may evolve. Pin exact versions for +evaluation and preserve evidence generated by each version.