If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/microsoft/QuantumKatas shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 34+ active contributors
• Distributed ownership (top contributor 19% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Scorecard: marked unmaintained (0/10)
• ⚠ Scorecard: default branch unprotected (0/10)

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests + OpenSSF Scorecard}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live microsoft/QuantumKatas repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/microsoft/QuantumKatas.

What it runs against: a local clone of microsoft/QuantumKatas — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in microsoft/QuantumKatas | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 655 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of microsoft/QuantumKatas. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/microsoft/QuantumKatas.git
#   cd QuantumKatas
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of microsoft/QuantumKatas and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "microsoft/QuantumKatas(\\.git)?\\b" \\
  && ok "origin remote is microsoft/QuantumKatas" \\
  || miss "origin remote is not microsoft/QuantumKatas (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "BasicGates/Tasks.qs" \\
  && ok "BasicGates/Tasks.qs" \\
  || miss "missing critical file: BasicGates/Tasks.qs"
test -f "BasicGates/Tests.qs" \\
  && ok "BasicGates/Tests.qs" \\
  || miss "missing critical file: BasicGates/Tests.qs"
test -f "BasicGates/ReferenceImplementation.qs" \\
  && ok "BasicGates/ReferenceImplementation.qs" \\
  || miss "missing critical file: BasicGates/ReferenceImplementation.qs"
test -f "GroversAlgorithm/README.md" \\
  && ok "GroversAlgorithm/README.md" \\
  || miss "missing critical file: GroversAlgorithm/README.md"
test -f ".github/CONTRIBUTING.md" \\
  && ok ".github/CONTRIBUTING.md" \\
  || miss "missing critical file: .github/CONTRIBUTING.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 655 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~625d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/microsoft/QuantumKatas"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

QuantumKatas is a collection of self-paced interactive tutorials and programming exercises for learning quantum computing and Q# programming. It provides step-by-step katas (coding challenges) with built-in unit tests, hints, and reference implementations, covering topics from basic quantum gates to advanced algorithms like Grover's and Shor's algorithms. Monorepo structure: each kata lives in its own top-level directory (BasicGates/, DeutschJozsaAlgorithm/, CHSHGame/, etc.), each containing a .csproj, .sln file for C#/QDK integration, a Tasks.qs file with exercise stubs, Tests.qs with unit tests, ReferenceImplementation.qs with solutions, and a .ipynb Jupyter notebook for interactive learning. Shared configuration via .vscode/ and .iqsharp-config.json.

Computer science students, developers, and researchers learning quantum computing fundamentals who want hands-on practice with Q# in an interactive, guided format with immediate feedback from unit tests. Contributors are quantum computing educators and Microsoft QDK maintainers adding new katas and tutorials.

Actively maintained but transitioning: the repo includes a deprecation notice directing users to the newer Azure Quantum katas online experience at quantum.microsoft.com and modern QDK at microsoft/qsharp. The codebase shows 2000+ Jupyter notebooks and 900K lines of Q# code, indicating substantial historical content. However, the deprecation signals this classic repository is in managed decline rather than active development.

Moderate risk: the project is being superseded by azure-quantum and modern QDK, so new features will not be added here. Dependencies include pinned versions (ipython==8.10.0, nbclient<=0.6.3, jinja2==3.0.3) that may accumulate security issues over time. The focus on Jupyter notebooks as primary delivery (2.1MB of notebook content) creates reproducibility concerns across Python/Jupyter versions.

The repository is in maintenance mode. The DEPRECATION NOTICE in README indicates active migration to the online platform at quantum.microsoft.com/experience/quantum-katas. Workflows include qdk-sync.yml (syncing with QDK updates) and devskim.yml (security scanning). No major new katas are being added; focus is on keeping existing content compatible with modern QDK.

git clone https://github.com/microsoft/QuantumKatas.git && cd QuantumKatas && pip install -r requirements.txt (based on dependencies: jupyter, qsharp, numpy, matplotlib, pytest). Then navigate to a kata folder (e.g., cd BasicGates/) and run 'jupyter notebook BasicGates.ipynb' to begin interactive exercises.

Daily commands: For Jupyter-based learning: 'jupyter notebook BasicGates/BasicGates.ipynb' opens the interactive notebook where you fill in Tasks.qs code and run test cells. For command-line testing: 'cd BasicGates && dotnet test' runs the Tests.qs unit tests via the QDK test framework.

• BasicGates/Tasks.qs — Entry point template for Q# kata exercises—defines the structure every contributor must follow for task definitions
• BasicGates/Tests.qs — Canonical test framework pattern used across all katas to validate student solutions
• BasicGates/ReferenceImplementation.qs — Reference solution template showing expected solution patterns and Q# idioms for kata design
• GroversAlgorithm/README.md — Comprehensive kata README template with learning objectives, hints, and narrative structure that sets the standard for all katas
• .github/CONTRIBUTING.md — Contribution guidelines defining how to add new katas, maintain quality standards, and align with Microsoft's quantum education mission
• BasicGates/BasicGates.csproj — C# project configuration template defining Q# SDK dependencies and build configuration inherited by all kata projects
• Dockerfile — Container specification for consistent development environment across contributors and CI/CD pipelines

Add a New Quantum Kata Exercise

1. Create a new kata directory (e.g., NewQuantumConcept/) following the standard structure (BasicGates/)
2. Copy and adapt Tasks.qs template defining exercise tasks with stub implementations (BasicGates/Tasks.qs)
3. Create Tests.qs with unit tests following the test framework pattern, one test per task (BasicGates/Tests.qs)
4. Write ReferenceImplementation.qs showing the complete solution using Q# idioms (BasicGates/ReferenceImplementation.qs)
5. Write README.md with background theory, hints, and learning objectives in narrative form (BasicGates/README.md)
6. Create .csproj project file by copying and renaming BasicGates.csproj (BasicGates/BasicGates.csproj)
7. Create Jupyter notebooks (.ipynb) from the notebook template for interactive learning (BasicGates/BasicGates.ipynb)
8. Update .github/CONTRIBUTING.md to reference the new kata and validate alignment with contribution standards (.github/CONTRIBUTING.md)

Enhance an Existing Kata with More Learning Content

1. Edit README.md to expand background theory, add diagrams, and provide more detailed hints for stuck students (BasicGates/README.md)
2. Update or create a Workbook_*.ipynb (e.g., Workbook_BasicGates.ipynb) with step-by-step explanations and visualizations (BasicGates/Workbook_BasicGates.ipynb)
3. Add new test cases to Tests.qs to cover edge cases and reinforce learning (BasicGates/Tests.qs)
4. Update ReferenceImplementation.qs with code comments explaining the quantum logic and best practices (BasicGates/ReferenceImplementation.qs)

Update Q# SDK Dependencies Across All Katas

1. Update qsharp and related packages in requirements.txt or .csproj files when QDK version changes (BasicGates/BasicGates.csproj)
2. Verify all kata .csproj files reflect the new SDK version consistently (BasicGates/BasicGates.csproj)
3. Run test suites in .github/workflows/qdk-sync.yml to validate compatibility (.github/workflows/qdk-sync.yml)
4. Document breaking changes in README.md files if Q# syntax or API changes (BasicGates/README.md)

• Q# (Quantum Development Kit) — Domain-specific language for quantum algorithm design and the primary learning target of all katas
• Jupyter Notebooks (.ipynb) — Interactive learning environment allowing students to edit Q# code, run tests, and see results inline without setup
• C# / .NET (csproj build system) — Underlying infrastructure for Q# compilation, testing framework, and integration with the Quantum Development Kit
• Python (pytest, dependencies) — Test orchestration, environment setup, and support for Jupyter kernel execution
• Docker — Ensures reproducible development and testing environment across all contributors and CI/CD pipelines
• GitHub Actions / Workflows — Automated testing and synchronization with upstream Quantum SDK updates

• Self-contained kata directories vs. centralized shared utilities

  • Why: Each kata is independent so students can learn one concept at a time without dependency chains or complex setup
  • Consequence: Some code duplication across katas (e.g., test patterns), but simpler onboarding and lower cognitive load per exercise

• Mix of Jupyter notebooks and command-line testing

  • Why: Notebooks offer interactive learning; CLI testing enables CI/CD and large-scale validation
  • Consequence: Contributors must maintain both .ipynb and .qs test files, but student experience is optimized

• Reference implementation alongside tasks

  • Why: Students can check solutions if stuck, supporting self-paced learning
  • Consequence: Requires discipline from students not to peek early; relies on honor system

• Monorepo structure (all katas in one repo) vs. separate kata repos

  • Why: Easier contribution workflow, shared CI/CD, unified versioning with QDK
  • Consequence: Repo grows large but remains browsable; no microrepo coordination overhead

• Does not provide cloud-hosted quantum hardware access or cloud simulator—relies on local Q# simulator
• Not a production framework for quantum application development (educational focus only)
• Does not offer automated code grading or student progress tracking (designed for self-paced learning)
• Not a formal university curriculum—no credit system or structured course prerequisites
• Does not provide real-time collaborative editing or peer review workflows (static content model)
• Does not support languages other than Q# (focused exclusively on Q# learning)

Jupyter kernel dependency: the .ipynb files require IQ# (the Q# kernel for Jupyter), which has specific version compatibility with qsharp and ipython (pinned to 8.10.0). Running notebooks on newer ipython may fail silently. The .iqsharp-config.json files are essential but easy to overlook when copying kata templates. QDK version mismatch: if qsharp SDK on your system is newer than the pinned qsharp package version, .csproj files may fail to restore dependencies. The repo uses both Jupyter notebooks AND C# projects in parallel; some katas have both BasicGates.ipynb and Workbook_BasicGates.ipynb with slight naming variations that can cause confusion.

• Quantum superposition — The foundation of quantum computing—understanding that qubits can be in multiple states simultaneously is required to understand why quantum algorithms outperform classical ones, which multiple katas teach
• Quantum entanglement — Critical for multi-qubit gates and algorithms like the CHSH game (CHSHGame kata); learners must grasp how entanglement creates correlations that have no classical analogue
• Unitary operators — All Q# operations are unitary transformations; understanding matrices and how quantum gates are represented as unitaries is essential for Tasks.qs implementations
• Phase kickback — Used in algorithms like Deutsch-Jozsa and Grover's; learners must understand how operations on control qubits can indirectly modify phase in register qubits without measuring them
• Oracle-based algorithm design — Many katas (Deutsch-Jozsa, Grover's, Simon's) build algorithms around 'black-box' oracle functions; learners must recognize this pattern and understand why it matters for quantum speedup
• Amplitude amplification — The core mechanism behind Grover's algorithm (covered in GroversAlgorithm kata); learners must understand how repeated reflections around the average amplify solution states

• microsoft/qsharp — The modern QDK replacement; this is where new Q# features and tools are being developed, and where QuantumKatas learners graduate to after mastering the basics
• microsoft/azure-quantum — Azure Quantum cloud platform that hosts the next-generation online katas experience; contains the successor learning platform QuantumKatas is being deprecated in favor of
• quantumcomputing/qiskit — Alternative quantum computing SDK (Python-based) with its own tutorials; useful for learners comparing Q# and Qiskit approaches to quantum algorithms
• Qiskit/qiskit-tutorials — Qiskit's equivalent tutorial repository; a parallel learning resource in the Python quantum computing ecosystem
• microsoft/quantum — Historical Microsoft quantum computing repository that preceded this katas repo; provides context on the evolution of Microsoft's quantum computing education strategy

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow to validate all kata exercises across multiple QDK versions

The repo has devskim.yml and qdk-sync.yml workflows, but lacks a main CI pipeline that runs Tests.qs files across all kata directories (BasicGates, DeutschJozsaAlgorithm, CHSHGame, etc.). This would catch regressions in ReferenceImplementation.qs and ensure exercises remain solvable. Given the deprecation notice and migration to Modern QDK, validating backward compatibility is critical.

• [ ] Create .github/workflows/test-katas.yml that discovers all */Tests.qs files
• [ ] Configure matrix strategy to test against multiple QDK versions (current stable + legacy)
• [ ] Add step to run qsharp test or dotnet test for each .csproj in kata directories
• [ ] Document expected test output in CONTRIBUTING.md with reference to specific katas
• [ ] Validate that all ReferenceImplementation.qs files pass their corresponding Tests.qs

Add Jupyter notebook validation to CI and fix deprecated ipython/nbclient versions

The repo contains multiple .ipynb files (BasicGates.ipynb, Workbook_*.ipynb) but no CI validation that these notebooks execute without errors. The dependencies pin ipython==8.10.0 and nbclient<=0.6.3, which are outdated and may have security issues. New contributors could add notebook linting/execution validation and upgrade these dependencies safely.

• [ ] Add nbval or papermill to test dependency list in Dockerfile and docs
• [ ] Create GitHub Action step that executes all *.ipynb files to catch broken cells
• [ ] Update ipython and nbclient to latest compatible versions, testing against q# kernel
• [ ] Add .github/workflows/notebook-validation.yml to run on pull requests
• [ ] Document any breaking changes in CONTRIBUTING.md if notebook syntax needs updates

Create missing .vscode configuration files for BoundedKnapsack, DistinguishUnitaries, GraphColoring, and GHZGame katas

BasicGates, CHSHGame, DeutschJozsaAlgorithm, and GHZGame have .vscode/extensions.json and .vscode/tasks.json files, but BoundedKnapsack, DistinguishUnitaries, and GraphColoring are missing these. This inconsistency creates a poor developer experience for newcomers using VS Code. Standardizing these files improves the onboarding experience and ensures all katas work with recommended extensions (Q# extension, Jupyter).

• [ ] Copy .vscode/extensions.json from BasicGates/ to BoundedKnapsack/, DistinguishUnitaries/, and GraphColoring/
• [ ] Adapt .vscode/tasks.json templates for each kata (update project names in csproj references)
• [ ] Verify tasks.json correctly references each kata's specific .csproj and Tests.qs file paths
• [ ] Test with VS Code to ensure build and test tasks run without errors for all 3 katas
• [ ] Add a note to CONTRIBUTING.md about the required .vscode structure for new katas

• Add missing unit tests to lesser-used katas: files like BoundedKnapsack/Tests.qs may have incomplete test coverage compared to BasicGates/Tests.qs. Review test patterns and add edge-case tests for boundary conditions.
• Migrate pinned ipython==8.10.0 and nbclient<=0.6.3 to compatible newer versions: review the jupyter/ipython API breaking changes since 8.10.0 and verify notebooks still run, then update requirements.txt and document any necessary code changes.
• Create a kata scaffolding script: write a Python or PowerShell script (in the repo root) that generates a new kata directory with template Tasks.qs, Tests.qs, .csproj, and .ipynb files, reducing boilerplate for contributors adding new exercises.

The QuantumKatas repository has several moderate-to-high severity security issues, primarily centered on outdated and potentially vulnerable Python dependencies (ipython==8.10.0, jinja2==3.0.3, nbclient<=0.6.3). The educational nature of the project reduces some risks, but these dependencies could pose risks if the katas are run in shared environments or if notebooks

• High · Outdated and Vulnerable IPython Dependency — Dependencies/Package file content - ipython==8.10.0. The dependencies specify ipython==8.10.0, which is significantly outdated (released in 2023). This version contains known security vulnerabilities including CVE-2023-24816 (arbitrary code execution via magic commands) and other RCE vectors. Fix: Update to the latest stable IPython version (13.0+) and regularly audit dependencies for security updates. Implement automated dependency scanning in CI/CD.
• High · Pinned Vulnerable Jinja2 Version — Dependencies/Package file content - jinja2==3.0.3. jinja2==3.0.3 is an outdated version that may contain security vulnerabilities. This version was released in 2021 and predates several known Jinja2 security fixes. Fix: Update to jinja2>=3.1.2 to receive security patches. Use flexible version pinning (e.g., jinja2>=3.1.2,<4.0) instead of strict pinning to old versions.
• High · Outdated nbclient with Version Constraint — Dependencies/Package file content - nbclient<=0.6.3. nbclient is pinned to <=0.6.3, which is outdated. This overly restrictive upper bound prevents access to security updates in newer versions. Fix: Remove or increase the upper version constraint to allow newer releases: nbclient>=0.6.3. Review why this constraint was added and update if no longer necessary.
• Medium · Unpinned PyZMQ Dependency — Dependencies/Package file content - pyzmq. pyzmq is listed without version constraints, which can lead to unexpected behavior changes or security vulnerabilities when a new version is installed in different environments. Fix: Pin pyzmq to a specific minimum version: pyzmq>=25.0 (or appropriate version based on compatibility testing).
• Medium · Missing pip Security Options in Dockerfile — Dockerfile - RUN pip install line. The Dockerfile uses 'pip install -I' but doesn't include '--require-hashes' or verify package integrity. The '--no-cache-dir' flag is good, but additional integrity checks are missing. Fix: Use pip's hash-checking mode (--require-hashes) for all production installs. Consider using a lock file (requirements.lock) generated by pip-tools to ensure reproducible, verified builds.
• Medium · Base Image Version Not Pinned — Dockerfile - FROM statement. The Dockerfile uses 'mcr.microsoft.com/quantum/iqsharp-base:0.28.302812' with an old tag. While a specific version is provided, this image may contain outdated dependencies and security patches. Fix: Verify the base image is still maintained and receives security updates. Consider using image digest hashing (SHA256) instead of tags for immutability and security.
• Low · Broad File Permissions on Scripts — Dockerfile - chmod +x line. The Dockerfile sets 'chmod +x ${HOME}/scripts/*.sh' on all shell scripts without validation. If any script is user-modifiable or comes from untrusted sources, this could be exploited. Fix: Explicitly chmod only known, trusted scripts. Verify script contents before making them executable. Consider running scripts with explicit interpreters instead of relying on executable bits.
• Low · Missing .sscignore Content Context — .sscignore. The .sscignore file is present but its contents are not provided. This file is typically used by security scanning tools, and its configuration is unknown. Fix: Review the .sscignore file to ensure it doesn't exclude important security-sensitive files from scanning.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.