unified-quantum 0.1.0__tar.gz

unified_quantum-0.1.0/.agents/skills/uniqc-build-docs/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: uniqc-build-docs
+description: "Run the full UnifiedQuantum documentation build: execute all examples (pre-doc-execution), regenerate API reference via sphinx-apidoc, and build Sphinx HTML. Reports any warnings, errors, or diffs in example-exec-logs/."
+---
+
+# UnifiedQuantum Documentation Build Skill
+
+Use this skill when a developer wants to build the documentation locally. The build has two stages:
+
+1. **Pre-doc-execution** (`scripts/build_docs.py`): runs every `examples/<chapter>/*.py`, captures stdout/stderr and matplotlib figures, generates `docs/source/_generated/examples/` Markdown pages, and refreshes `example-exec-logs/`.
+2. **Sphinx HTML** (`sphinx-build`): builds the final site, `{include}`-ing the generated example pages.
+
+`make html` runs both. `make html-fast` skips step 1 and trusts committed logs.
+
+## Steps
+
+### Step 1: Ensure the environment is up to date
+
+From the project root:
+
+```bash
+uv sync --all-extras --group dev --group docs
+```
+
+If `uv sync` fails because of an unresolvable optional extra, retry without `--all-extras`:
+
+```bash
+uv sync --group dev --group docs
+```
+
+### Step 2: Run the full doc build
+
+From the project root:
+
+```bash
+cd docs && uv run make html 2>&1
+```
+
+This runs (in order):
+1. `examples` target — executes `scripts/build_docs.py` and refreshes `example-exec-logs/`
+2. `apidoc` target — runs `sphinx-apidoc` to regenerate API rst stubs under `source/6_api/`
+3. `html` target — runs `sphinx-build -M html`
+
+Capture the full output and look for:
+- **`WARNING`** or **`ERROR`** lines from Sphinx
+- **Traceback** or **Exception** lines from example execution
+- **Non-zero exit code** from `make html`
+
+### Step 3: Check for example-exec-logs diffs
+
+After a successful build, check whether the committed example outputs changed:
+
+```bash
+git diff --stat -- example-exec-logs/
+```
+
+- **No diff**: examples produced identical output to what is committed. No action needed.
+- **Diff present**: an example's behaviour changed. Review the diff to confirm it is intentional (due to your code changes), then stage and commit the updated logs:
+  ```bash
+  git add example-exec-logs/
+  ```
+
+### Step 4: Check for generated-page diffs
+
+```bash
+git diff --stat -- docs/source/_generated/
+```
+
+Commit any intentional diffs:
+
+```bash
+git add docs/source/_generated/
+```
+
+### Step 5: Report results
+
+Report to the user:
+1. Whether the build succeeded (exit code 0) or failed.
+2. Number and category of warnings (if any).
+3. Whether `example-exec-logs/` has uncommitted diffs (and whether they were committed).
+4. Path to the built HTML: `docs/_build/html/index.html`.
+
+## Fast rebuild (skip example re-execution)
+
+If examples have not changed and only prose or API docs were edited, use the fast path:
+
+```bash
+cd docs && uv run make html-fast 2>&1
+```
+
+This skips `scripts/build_docs.py` and uses the already-committed `example-exec-logs/`.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `ModuleNotFoundError` during example execution | Missing optional dependency | `uv sync --all-extras --group docs` or install the specific package |
+| `WARNING: unknown directive` in Sphinx output | Missing or renamed rst/md include path | Check `docs/source/<chapter>/index.md` for stale `{include}` paths |
+| `example-exec-logs/` diff on CI but not locally | Stale committed logs | Run `make html` locally, commit updated `example-exec-logs/` |
+| `sphinx-apidoc` produces unexpected entries | New module not excluded | Update `APIDOC_EXCLUDE` in `docs/Makefile` |

unified_quantum-0.1.0/.agents/skills/uniqc-release/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: uniqc-release
+description: "Create a new UnifiedQuantum release: generates release notes, updates CHANGELOG.md, creates a release branch, and opens a PR to main. After merge, creates and pushes a git tag, creates a GitHub Release, and deletes the release branch."
+---
+
+# UnifiedQuantum Release Skill
+
+Use this skill when a maintainer wants to create a new release. The release workflow has two phases: PR creation and post-merge publication.
+
+**Note**: PyPI publishing is automatic via GitHub Actions when a `v*` tag is pushed. GitHub Release is created as part of the post-merge workflow.
+
+## Version Number
+
+**IMPORTANT**: If the user does NOT provide a version number, you MUST ask them for one before proceeding.
+
+Valid version formats:
+- `vx.y.z` (e.g., `v0.0.10`)
+- `x.y.z` (e.g., `0.0.10`)
+
+The version will be normalized to `vx.y.z` format.
+
+## Phase 1: Pre-Merge (Release PR)
+
+### Step 1: Check Preconditions
+
+1. Confirm we're on `main` branch and worktree is clean:
+   ```bash
+   git status
+   git branch
+   ```
+
+2. Check current version from `uniqc/_version.py`:
+   ```bash
+   grep "__version__" uniqc/_version.py
+   ```
+
+3. Verify CHANGELOG.md has `[Unreleased]` section with content.
+
+### Step 2: Generate Release Notes
+
+Run the release notes generator (if available):
+```bash
+uv run python scripts/generate_release_notes.py <version> 2>/dev/null || echo "No release notes generator found"
+```
+
+If no generator exists, manually draft release notes from:
+- `CHANGELOG.md` `[Unreleased]` section
+- Recent commit messages: `git log --oneline --since="2 weeks ago"`
+
+### Step 3: Update CHANGELOG.md
+
+1. Read current `CHANGELOG.md` to find the `[Unreleased]` section
+2. Add the new version section with today's date:
+   ```
+   ## [x.y.z] - YYYY-MM-DD
+
+   [Content from Unreleased section]
+   ```
+3. Update the `[Unreleased]` section to be empty (or add placeholder)
+
+### Step 4: Update Documentation Release Notes
+
+1. Read current `docs/source/7_releases/index.md`
+2. Add a new version section under `## 版本解读` with:
+   - **Version heading**: `### v{x.y.z}`
+   - **Summary paragraph**: Brief description of the release theme
+   - **Changes list**: Key additions, changes, and fixes
+   - **Migration notes**: If breaking changes exist, add upgrade guidance
+   - **Known gaps**: Document any unverified features
+   - **Verification results**: Link to test report if available
+3. Update the header section:
+   - Change "当前建议先看哪个版本" to point to the new version
+   - Update the version description to reflect the new release
+
+Example structure:
+```markdown
+### `v{x.y.z}`
+
+这是一个[X类]版本，核心主题是**主题描述**。
+
+本版主要变更：
+- **变更1**：描述
+- **变更2**：描述
+
+如果你正在从 `v{prev}` 迁移，主要变更对用户透明：
+- 变更说明
+
+已知缺口（不阻塞发布）：
+- 缺口描述
+
+**发布验证结果**：验证结果摘要。
+```
+
+### Step 5: Create Release Branch
+
+```bash
+git checkout -b release/<version>
+```
+
+### Step 6: Commit Changes
+
+```bash
+git add CHANGELOG.md docs/source/7_releases/index.md
+git commit -m "$(cat <<'EOF'
+docs(release): prepare v{x.y.z} release
+
+- Update CHANGELOG.md with release notes
+- Move [Unreleased] changes to [{x.y.z}] section
+- Add release notes to docs/source/7_releases/index.md
+EOF
+)"
+```
+
+### Step 7: Push and Create PR
+
+```bash
+git push -u origin release/<version>
+gh pr create --title "Release v{x.y.z}" --body "$(cat <<'EOF'
+## Release v{x.y.z}
+
+### Changes
+[Summary of changes from CHANGELOG.md]
+
+### Pre-release Testing
+- [x] `uniqc-test-before-release` skill completed
+- [x] Test report reviewed and approved
+- [x] All blocking issues resolved
+
+### Release Checklist
+- [ ] PR merged to main
+- [ ] GitHub Actions CI passes
+- [ ] Tag created and pushed
+- [ ] PyPI publication confirmed
+EOF
+)"
+```
+
+## Phase 2: Post-Merge (Publication)
+
+**IMPORTANT**: After the PR is merged, ask the user to confirm before proceeding.
+
+### Step 1: Confirm User Intent
+
+Ask the user: "The PR has been merged. Do you want me to proceed with creating the tag, GitHub Release, and cleaning up?"
+
+### Step 2: Fetch and Checkout Main
+
+```bash
+git fetch origin main
+git checkout main
+git pull origin main
+```
+
+### Step 3: Create and Push Tag
+
+```bash
+git tag -a v{x.y.z} -m "Release v{x.y.z}"
+git push origin v{x.y.z}
+```
+
+GitHub Actions will automatically:
+1. Build wheels for Ubuntu and Windows
+2. Validate wheel ABI
+3. Publish to PyPI
+
+### Step 4: Create GitHub Release
+
+```bash
+gh release create v{x.y.z} \
+  --title "v{x.y.z}" \
+  --notes-file <(cat <<'EOF'
+## Changes
+
+See CHANGELOG.md for details.
+
+## What's Changed
+
+[Summary from release notes]
+EOF
+)
+```
+
+Or use the GitHub web UI to create the release after the tag is pushed.
+
+### Step 5: Delete Release Branch
+
+```bash
+git branch -D release/v{x.y.z}
+git push origin --delete release/v{x.y.z}
+```
+
+### Step 6: Verify
+
+```bash
+# Check the tag exists
+git fetch --tags
+git tag -l "v{x.y.z}*"
+```
+
+Monitor the release at:
+- GitHub Actions: https://github.com/IAI-USTC-Quantum/UnifiedQuantum/actions
+- GitHub Releases: https://github.com/IAI-USTC-Quantum/UnifiedQuantum/releases
+- PyPI: https://pypi.org/project/unified-quantum/
+
+## Error Handling
+
+- If CHANGELOG.md is missing or malformed, create a minimal release note
+- If the branch already exists, offer to delete and recreate or use existing
+- If tag push fails, retry or inform the user
+- If GitHub Release creation fails, inform user to create it manually at the releases page
+
+## Example Conversation Flow
+
+1. User: "Run the uniqc-release skill" (or otherwise asks to create a release)
+2. Assistant: "What version would you like to release? (Current: 0.0.9)"
+3. User: "0.0.10"
+4. Assistant: Creates release PR...
+5. User merges PR
+6. Assistant: "PR merged! Shall I create the tag, GitHub Release, and clean up?"
+7. User: "Yes"
+8. Assistant: Creates tag → GitHub Actions publishes to PyPI → Creates GitHub Release → Deletes release branch

unified_quantum-0.1.0/.agents/skills/uniqc-test-before-release/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: uniqc-test-before-release
+description: "Use before every UnifiedQuantum release to create and execute a complete release-candidate test plan, including CLI, Gateway frontend, cloud/dummy/real-device workflows, best-practices notebooks, and programmatic documentation-to-software alignment. Produces a full test report and a release/no-release recommendation."
+---
+
+# UnifiedQuantum Pre-Release Test Skill
+
+Use this skill when a maintainer asks for release-candidate validation. This is not a smoke test. The output must be a complete execution plan first, then a complete report with a clear release recommendation.
+
+## Required Output
+
+Produce two artifacts:
+
+1. **Test execution plan**: exact commands, credentials/quotas needed, expected artifacts, and pass/fail criteria.
+2. **Final release report**: what was tested, evidence, failures, doc/software mismatches, coverage gaps, and one of `RELEASE`, `RELEASE WITH KNOWN GAPS`, or `DO NOT RELEASE`.
+
+Use [references/report-template.md](references/report-template.md) for the report shape. Use [references/coverage-matrix.md](references/coverage-matrix.md) to avoid missing functional areas.
+
+## First Steps
+
+1. Confirm the release candidate:
+   - Current branch, commit, tag candidate, and version from `uniqc/_version.py` or package metadata.
+   - `README.md`, `README_en.md`, `CHANGELOG.md`, `pyproject.toml`, and `docs/source/7_releases/`.
+2. Check the worktree:
+   - `git status -sb`
+   - Do not mix unrelated local changes into the release report. Report them as environment risk if they affect execution.
+   - Scan the repository root for stale release artifacts: `RELEASE_REPORT_*.md` and `RELEASE_EXECUTION_PLAN_*.md` whose version does **not** match the release under validation (e.g. `RELEASE_REPORT_0.0.15.md` while validating `0.0.16`). Stale artifacts are a **blocking issue** — they must be removed (or the removal PR merged) before tagging. Only the current release's report and plan may sit in the root at tag time.
+3. Build the test environment:
+   - `uv sync --extra all --group dev --group docs --upgrade`
+   - `cd frontend && npm ci`
+   - `[quark]` requires Python ≥ 3.12 and ships wheels for Linux/macOS/Windows; it is included in `[all]` on supported interpreters.
+4. Identify real-platform readiness:
+   - Config file: `~/.uniqc/config.yaml`
+   - Required token sections: `originq`, `ibm`, `quark`, plus `tianyan` / `logicalqubit` when those platforms are in scope.
+   - Confirm quota/cost permission before any command that submits a real quantum task.
+
+## Mandatory Test Phases
+
+### 1. Automated Python Package Tests
+
+Run and record:
+
+```bash
+uv run pytest uniqc/test -v
+uv run pytest uniqc/test -v --real-cloud-test
+```
+
+Rules:
+
+- Ordinary cloud discovery/status/token tests must run in the default test command.
+- Only tests that submit real quantum circuits belong behind `--real-cloud-test`.
+- Dependency failures for maintained extras such as Qiskit, Qutip, Torch, docs, or visualization are release blockers unless the maintainer explicitly scopes them out.
+
+### 2. C++ Simulator Dependency Check
+
+The C++ simulator extension lives in the separate [`uniqc-cppsimulator`](https://github.com/IAI-USTC-Quantum/uniqc-cppsimulator) package (import name `uniqc_cpp`), which ships its own wheels and type stubs; `scripts/stubgen.py` no longer exists in this repository. Verify the installed dependency imports and exposes the simulator classes:
+
+```bash
+uv run python -c "import uniqc_cpp; print(uniqc_cpp.StatevectorSimulator, uniqc_cpp.DensityOperatorSimulator)"
+```
+
+### 3. Best-Practices Documentation Execution
+
+The best-practices section is a release gate.
+
+Run:
+
+```bash
+uv run python scripts/build_docs.py --only 3_best_practices
+cd docs
+uv run make html
+```
+
+Then inspect:
+
+- `docs/source/1_basic_usage/best_practices.md`
+- `docs/source/3_best_practices/index.md`
+- every generated chapter under `docs/source/_generated/examples/3_best_practices/*.md`
+- generated HTML pages for broken rendering, stale outputs, or inconsistent command names.
+
+Best-practices failures are blockers unless the affected feature is explicitly removed from the release.
+
+### 4. CLI Help and CLI Behavior
+
+Use CLI help as a progressive-disclosure source of truth. Capture help for the root command and every public subcommand:
+
+```bash
+uv run uniqc --help
+uv run python -m uniqc.cli --help
+uv run uniqc circuit --help
+uv run uniqc simulate --help
+uv run uniqc submit --help
+uv run uniqc result --help
+uv run uniqc config --help
+uv run uniqc task --help
+uv run uniqc backend --help
+uv run uniqc backend list --help
+uv run uniqc backend show --help
+uv run uniqc backend update --help
+uv run uniqc backend chip-display --help
+uv run uniqc calibrate --help
+uv run uniqc gateway --help
+uv run uniqc sync --help
+uv run uniqc doctor --help
+```
+
+Then execute representative CLI workflows:
+
+- Build or write a Bell/GHZ OriginIR file. Prefer OriginIR in release-plan examples because it is the recommended normalized path:
+
+```originir
+QINIT 2
+CREG 2
+H q[0]
+CNOT q[0], q[1]
+MEASURE q[0], c[0]
+MEASURE q[1], c[1]
+```
+
+- `uv run uniqc circuit <file> --info`
+- `uv run uniqc simulate <file>`
+- `uv run uniqc submit <file> --backend dummy:local:simulator --wait`
+- `uv run uniqc submit <file> --backend dummy:local:virtual-line-3 --wait`
+- `uv run uniqc submit <file> --backend dummy:originq:WK_C180 --dry-run`
+- `uv run uniqc backend update --platform originq`
+- `uv run uniqc backend list --platform originq`
+- `uv run uniqc backend show originq:WK_C180`
+- `uv run uniqc backend chip-display originq/WK_C180 --update`
+
+Note: `uniqc submit` takes a single `--backend BACKEND_ID` flag (no
+`--platform` option). `uniqc backend list/update`, `uniqc task list`, and
+`uniqc result` *do* accept `--platform`.
+
+Confirm the docs match the help output and actual behavior. Do not recommend `python -m uniqc`; the supported module fallback is `python -m uniqc.cli`. There is no `uniqc workflow` CLI subcommand; `docs/source/4_cli/workflow.md` is a workflow guide page, and interactive next-step guidance is exposed by `--ai-hints` / `--ai-hint`.
+
+Also verify the AI-hint paths:
+
+- `uv run uniqc config list --ai-hint` or an equivalent command-local hint check.
+- `uv run uniqc config always-ai-hint on`
+- A subsequent command without `--ai-hint` prints AI workflow hints.
+- `uv run uniqc config always-ai-hint off`
+- Error-path documentation recommends adding `--ai-hint` or enabling `always-ai-hint` when an agent is uncertain about the next command.
+
+### 5. Gateway Frontend and API
+
+Run frontend checks:
+
+```bash
+cd frontend
+npm run build
+```
+
+Run gateway checks:
+
+```bash
+uv run uniqc gateway status
+uv run uniqc gateway start --host 127.0.0.1 --port 18765
+```
+
+Then verify:
+
+- `/api/health`
+- `/api/version`
+- `/api/backends`
+- `/api/tasks`
+- the React app renders built assets from `frontend/dist`.
+- Backend cards do not list `dummy:<platform>:<backend>` as an enumerable backend.
+- Task pages can show dummy tasks, dry-run metadata where applicable, and compiled/transpiled metadata for chip-backed dummy paths.
+
+Use Playwright or an available browser automation tool if present. If no browser tool is available, use HTTP responses and built asset inspection, and mark visual coverage as a gap.
+
+### 6. Real-Platform Validation
+
+Separate real-platform tests into three buckets:
+
+- **Discovery**: backend list, status, token validation, and cache update. This should run by default in a core-dev environment.
+- **Dry-run**: compatibility checks without creating quantum tasks.
+- **Execution**: small-shot real quantum tasks. Requires explicit maintainer permission, quota notes, task IDs, and result retrieval.
+
+Minimum release-candidate evidence:
+
+- At least one OriginQ discovery/cache/dry-run path.
+- At least one IBM/Qiskit discovery or documented reason it is unavailable.
+- At least one real quantum task if the maintainer has authorized quota use.
+- For every unavailable platform, record the exact missing token, SDK, region, or network reason.
+
+### 7. Programmatic Documentation Alignment
+
+Compare docs to software, not just by reading prose.
+
+Check at least:
+
+- `pyproject.toml` `project.scripts` contains `uniqc = "uniqc.cli.main:app"` and docs use `uniqc` / `python -m uniqc.cli`.
+- CLI docs under `docs/source/4_cli/` describe commands that exist in `uv run uniqc --help`.
+- Best-practices code imports current top-level APIs from `uniqc` where expected.
+- New docs do not encourage old entries for new code: `uniqc.transpiler`, `uniqc.task`, `uniqc.qasm`, `uniqc.originir`, `uniqc.pytorch`, `uniqc.analyzer`.
+- Dummy backend semantics are consistent:
+  - `dummy`: unconstrained, noiseless local VM.
+  - `dummy:local:virtual-line-N` / `dummy:local:virtual-grid-RxC`: virtual topology, noiseless.
+  - `dummy:<platform>:<backend>`: rule-based chip-backed local noisy execution, not listed as an enumerable backend.
+- Config path is `~/.uniqc/config.yaml`.
+- AI workflow hints use `--ai-hints` / `--ai-hint`, environment variable `UNIQC_AI_HINTS=1`, or `uniqc config always-ai-hint on`.
+- IBM proxy can be configured with nested config keys such as `uniqc config set ibm.proxy.https http://127.0.0.1:7890`.
+- `[quark]` requires Python ≥ 3.12 and is included in `[all]` on supported interpreters.
+
+When possible, write small one-off scripts for this comparison and include their output in the report. If a comparison is manual, label it manual.
+
+## Release Recommendation Rules
+
+Use `DO NOT RELEASE` when any of these are true:
+
+- Best-practices notebooks or docs build fail for maintained paths.
+- CLI public help and docs disagree on a command required by the recommended workflow.
+- Gateway frontend cannot build or the Gateway API cannot start in the release environment.
+- Default tests fail for maintained dependencies.
+- Real-platform discovery or dry-run fails without a documented external cause.
+- Documentation claims a workflow works, but execution proves it does not.
+- Stale release artifacts from earlier releases (`RELEASE_REPORT_<older-version>.md`, `RELEASE_EXECUTION_PLAN_<older-version>.md`) remain in the repository root; only the current release's artifacts may be present.
+
+Use `RELEASE WITH KNOWN GAPS` only when the gaps are external, explicitly documented, and not on the recommended path.
+
+Use `RELEASE` only when the mandatory phases pass and any untested area is non-release-critical with maintainer approval.

unified_quantum-0.1.0/.agents/skills/uniqc-test-before-release/references/coverage-matrix.md

@@ -0,0 +1,25 @@
+# Coverage Matrix
+
+Use this checklist when generating the detailed execution plan and final report.
+
+| Area | Minimum checks | Release blocker examples |
+|---|---|---|
+| Install | `uv sync --all-extras --group dev --group docs --upgrade`; package import; CLI entry present | maintained extra cannot resolve; `uniqc` command missing |
+| Python API | `Circuit`, top-level imports, compile/transpile, simulator, task manager | recommended import path broken; compile produces invalid circuit |
+| Dummy backends | `dummy`, `dummy:local:virtual-line-N`, `dummy:local:virtual-grid-RxC`, `dummy:<platform>:<backend>` | chip-backed dummy listed as enumerable backend; topology constraints ignored |
+| CLI | root help, subcommand help, simulate, submit, result, config, task, backend, calibrate, gateway, `--ai-hint(s)`, `config always-ai-hint` | docs command missing from help; nonexistent `workflow` command tested as real CLI; `python -m uniqc.cli` broken |
+| Best practices | regenerate notebooks; inspect all `docs/source/best_practices/*.ipynb`; build docs | notebook execution failure; stale outputs; docs contradict behavior |
+| Docs alignment | CLI help vs docs; pyproject scripts vs docs; deprecated imports scan | docs recommend removed command/API; config path mismatch |
+| Gateway backend | `uniqc gateway start/status`; `/api/health`; `/api/version`; `/api/backends`; `/api/tasks` | server cannot start; API schema incompatible with frontend |
+| Gateway frontend | `npm ci`; `npm run build`; loaded built app; backend/task pages | TypeScript build failure; blank frontend; backend cards wrong |
+| Cloud discovery | OriginQ/IBM/Quark token/status/list/cache update where configured; IBM proxy config path if needed | configured platform cannot list backends without external cause |
+| Real execution | authorized small-shot real task; task ID; result retrieval; cache record | submitted task cannot be queried; result normalizer broken |
+| Calibration/QEM/XEB | readout/XEB dummy path; calibration cache; QEM TTL behavior | calibration file unusable; QEM silently uses stale data |
+| Persistence | task cache, backend cache, archive store, config profiles | cache corruption, wrong profile, task lost after restart |
+
+Coverage labels:
+
+- `PASS`: executed and matched expected behavior.
+- `FAIL`: executed and failed.
+- `BLOCKED`: external missing credential, quota, network, or SDK; include exact blocker.
+- `NOT RUN`: not attempted; include why and who accepted the risk.

unified_quantum-0.1.0/.agents/skills/uniqc-test-before-release/references/report-template.md

@@ -0,0 +1,93 @@
+# Pre-Release Test Report Template
+
+Use this exact top-level structure. Keep evidence concrete: command, commit, artifact path, task ID, or URL.
+
+## Verdict
+
+Recommendation: `RELEASE` / `RELEASE WITH KNOWN GAPS` / `DO NOT RELEASE`
+
+One-paragraph rationale.
+
+## Release Candidate
+
+- Repository:
+- Branch:
+- Commit:
+- Tag/version candidate:
+- Test start/end time:
+- Tester/agent:
+- Machine/OS/Python/Node:
+
+## Executive Summary
+
+| Area | Status | Evidence | Notes |
+|---|---|---|---|
+| Python tests |  |  |  |
+| Best practices |  |  |  |
+| CLI |  |  |  |
+| AI hints |  |  |  |
+| Docs alignment |  |  |  |
+| Gateway frontend |  |  |  |
+| Gateway API |  |  |  |
+| Cloud discovery |  |  |  |
+| Real-device execution |  |  |  |
+| Calibration/QEM/XEB |  |  |  |
+
+## Blocking Issues
+
+List release blockers first. For each item include:
+
+- Severity:
+- Affected area:
+- Evidence:
+- Reproduction:
+- Expected:
+- Actual:
+- Suggested owner/fix:
+
+## Non-Blocking Gaps
+
+List accepted gaps. Include who accepted the risk and why it does not block release.
+
+## Environment and Setup
+
+Include dependency commands, package versions, `uv run uniqc --version` if available, `uv run uniqc --help` availability, and frontend dependency state.
+
+## Best-Practices Validation
+
+For each best-practices notebook:
+
+- File:
+- Execution status:
+- Key output checked:
+- Doc/software mismatch found:
+
+End with a statement on whether the best-practices chapter is aligned with software behavior.
+
+## CLI Validation
+
+Include captured help commands and behavioral CLI workflows. Explicitly state whether the docs match the help output.
+
+Also include whether `--ai-hints` / `--ai-hint`, `UNIQC_AI_HINTS=1`, and `uniqc config always-ai-hint on` were checked.
+
+## Gateway Frontend/API Validation
+
+Include build result, server command, API endpoints checked, frontend rendering method, and any visual testing gaps.
+
+## Cloud and Real-Device Validation
+
+Separate discovery, dry-run, and real execution. For real tasks include backend, shots, task ID, submission time, result retrieval time, and result summary.
+
+## Programmatic Documentation Alignment
+
+Describe every scripted or manual comparison:
+
+- Comparison:
+- Source files:
+- Command/script:
+- Result:
+- Mismatches:
+
+## Final Recommendation
+
+Repeat the verdict and list the exact conditions that must change before release if the answer is not `RELEASE`.

unified_quantum-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

unified_quantum-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,5 @@
+# Copilot instructions
+
+See [`AGENTS.md`](../AGENTS.md) at the repository root. It is the single
+source of truth for agent-facing project instructions (environment, testing,
+architecture, and repo conventions) and is kept tool-neutral.