readiness-as-code 0.7.0__py3-none-any.whl

readiness_as_code-0.7.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: readiness-as-code
+Version: 0.7.0
+Summary: Know before you ship — continuous readiness as a folder in your repo.
+Author: Jeremiah Walters
+License: MIT
+Project-URL: Homepage, https://github.com/jtwalters25/readiness-as-code
+Project-URL: Documentation, https://github.com/jtwalters25/readiness-as-code/tree/main/docs
+Project-URL: Repository, https://github.com/jtwalters25/readiness-as-code
+Project-URL: Issues, https://github.com/jtwalters25/readiness-as-code/issues
+Keywords: compliance,code-review,quality-gates,operational-readiness,devops,ci-cd,policy-as-code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == "mcp"
+Dynamic: license-file
+
+<p align="center">
+  <img src="docs/assets/banner.svg" alt="ready" width="600" />
+</p>
+
+<h3 align="center">
+  AI tools made your team faster. They didn't make your team safer.
+</h3>
+
+<p align="center">
+  <strong>ready</strong> is the discipline layer that keeps pace with AI velocity —<br/>
+  review criteria as committed definitions, evaluated on every change,<br/>
+  with drift detected automatically before it becomes an incident.
+</p>
+
+<p align="center">
+  No infrastructure. No SaaS. No subscription.<br/>
+  JSON definitions + Python scanner + CI template.
+</p>
+
+<p align="center">
+  <a href="#quickstart">Quickstart</a> •
+  <a href="docs/getting-started.md">Docs</a> •
+  <a href="docs/architecture-and-tradeoffs.md">Architecture</a> •
+  <a href="docs/verification-types.md">Verification Types</a> •
+  <a href="docs/ci-integration.md">CI Integration</a>
+</p>
+
+<p align="center">
+  <a href=".readiness/review-baseline.json">
+    <img src="https://img.shields.io/badge/ready-100%25-brightgreen" alt="ready: 100%" />
+  </a>
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
+</p>
+
+---
+
+## Connect with Jeremiah Walters
+
+[![LinkedIn](https://img.shields.io/badge/linkedin-jeremiahwalters-blue?style=for-the-badge&logo=linkedin)](https://www.linkedin.com/in/jeremiahwalters)
+[![Twitter](https://img.shields.io/badge/twitter-@Afrotechnician-1da1f2?style=for-the-badge&logo=twitter)](https://x.com/Afrotechnician)
+
+## The Problem: Velocity Outran Discipline
+
+AI coding tools removed the friction from writing and shipping code. They did not remove the friction from the discipline work — health checks, secrets hygiene, on-call registration, telemetry coverage, auth on every endpoint. Velocity is now AI-speed. Discipline is still person-speed. The gap between the two is where incidents live.
+
+Production breakdowns keep hitting strong engineering orgs — not because they lack talent, but because velocity outran the scaffolding. Smart teams moved fast, skipped the prep work, and found out later that the checks weren't there. `ready` is the tool that implements this practice. It replaces **prep work**, not judgment.
+
+## Before / After
+
+| Before | After |
+|--------|-------|
+| AI writes code in seconds; readiness checks take hours | Readiness checks run in the same pipeline, same pace |
+| Manual checklists that can't keep up with AI velocity | Automated scan on every PR — no human bottleneck |
+| Point-in-time review ceremonies | Continuous compliance, not a quarterly ritual |
+| Drift detected by incidents | Drift detected before merge |
+| Tribal knowledge of what's missing | Structured gap list with file-path evidence |
+| "Are we ready?" is a subjective question | "Are we ready?" has a deterministic answer |
+| Accepted risks forgotten over time | Accepted risks expire and re-surface automatically |
+
+## Quickstart
+
+```bash
+pip install readiness-as-code
+
+cd your-repo
+ready scan
+```
+
+> **Windows / PATH issues?** Use `python -m ready scan` — works anywhere Python is installed.
+
+```
+ready? — your-service   80%   1 blocking · 2 warnings
+
+  ✗ No secrets in code
+    src/config.py:14
+    → Remove hardcoded keys. Use environment variables or a secrets manager.
+
+  + 2 warnings   (ready scan --verbose)
+```
+
+**No config. No accounts. No init required.** `ready scan` auto-detects your project type and runs immediately. When you're ready to customize, run `ready init`.
+
+When everything is passing:
+
+```
+ready? — your-service   100%   ✓   ▲ +12%
+```
+
+One line. The drift indicator appears automatically whenever a committed baseline exists.
+
+## Origin
+
+Built from production use managing 86+ readiness checkpoints across enterprise reliability engineering at scale. This is the vendor-neutral, portable version of a system that enforces production readiness across real services handling real incidents — not a weekend experiment.
+
+## How It Works
+
+```
+your-repo/
+└── .readiness/
+    ├── checkpoint-definitions.json   # What to check
+    ├── exceptions.json               # Accepted risks + expiry
+    ├── external-evidence.json        # Human attestations for non-code artifacts
+    └── review-baseline.json          # Last scan snapshot (committed = audit trail)
+```
+
+Four JSON files and a scanner. Checkpoints resolve through three verification types: **code checks** (grep/glob/file_exists against the repo), **external checks** (human attestations for artifacts outside the repo), and **hybrid checks** (both must pass). → [Architecture details](docs/architecture-and-tradeoffs.md) · [Verification types](docs/verification-types.md)
+
+## Checkpoint Packs
+
+Start with a curated pack, then customize:
+
+```bash
+ready init                                   # Universal starter (default)
+ready init --pack web-api                    # REST/HTTP API checks
+ready init --pack security-baseline          # Secrets, dependency hygiene, security policy
+ready init --pack telemetry                  # Logging, tracing, metrics, dashboards
+ready init --pack engineering-review         # Full engineering review (arch, security, testing, AI/RAI)
+ready init --pack operational-review         # Operational readiness (SLOs, on-call, data, capacity)
+ready init --pack governance                 # SDLC gates + external review attestations
+ready init --pack service-migration          # Service identity migration, auth provisioning, cutover
+ready init --list-packs                      # Show all available packs
+```
+
+| Pack | Checks | Best for |
+|------|--------|----------|
+| `starter` | 11 | Any repo |
+| `web-api` | 17 | REST/HTTP services |
+| `security-baseline` | 8 | Any repo with sensitive data |
+| `telemetry` | 8 | Production services |
+| `engineering-review` | 26 | Pre-launch engineering review |
+| `operational-review` | 14 | Pre-launch operational review |
+| `governance` | 15 | SDLC compliance + sign-off tracking |
+| `service-migration` | 9 | Service identity migration + cutover |
+
+## Proven in Production
+
+ready is based on a system used in enterprise reliability engineering environments, 
+enforcing 80+ readiness checkpoints across real services.
+
+It has been used to:
+- continuously evaluate production readiness across services
+- detect regression before deployment
+- reduce reliance on manual review preparation
+
+This open-source version is the portable, vendor-neutral implementation.
+
+## Key Capabilities
+
+- **Auto-drift detection.** If a committed baseline exists, every scan shows a delta: `▲ +12%` or `▼ -5%`. No flags, no extra commands.
+- **Closed-loop work item tracking.** Gaps become tracked work items (GitHub, Azure DevOps, Jira); ticket-closed-but-code-failing flags as **regression**, code-fixed-but-ticket-open as **stale**.
+- **Cross-repo aggregation.** `ready aggregate` turns multiple baselines into an HTML heatmap — *"telemetry gaps in 4 of 5 services"* is a platform problem, not a team problem.
+- **Expiring accepted risks.** Acknowledge a gap with a justification and expiry date; the scanner re-flags it when the expiry passes.
+- **Readiness audit.** `ready audit` reports the health of the readiness system itself — exception age, definition staleness, review_by coverage, score trend.
+- **Codebase-aware inference.** `ready infer` analyzes stack, frameworks, dependencies, ADRs, and auth patterns to propose tailored checkpoints you approve one at a time.
+- **AI-assisted authoring.** `ready author --from guidelines.md` generates a paste-ready prompt for any model (Claude, ChatGPT, Copilot, Cursor, Gemini).
+- **README badge.** `ready badge` generates a shields.io badge from the committed score.
+- **CI gating.** Non-zero exit on red failures; templates for GitHub Actions, Azure Pipelines, GitLab CI. → [Details](docs/ci-integration.md)
+- **Azure DevOps extension.** Pipeline task publishes each checkpoint as a test case, plus a dashboard widget for score, trend, and blocking count. → [Details](ado-extension/README.md)
+
+## What This Is Not
+
+- **Not a static analysis tool.** SonarQube checks code quality. This checks whether your service meets its review requirements.
+- **Not a policy engine.** OPA/Sentinel enforce infra policies at deploy time. This tracks operational and engineering readiness across code and non-code artifacts.
+- **Not a compliance SaaS.** Drata/RegScale automate regulatory frameworks. This enforces your team's own internal review standards.
+- **Not a replacement for AI coding tools.** It's the complement to them — the discipline layer that keeps pace with the velocity they enable.
+- **Not a replacement for review meetings.** This replaces the prep work so the meeting can focus on judgment calls the scanner can't make.
+
+## Commands
+
+```bash
+# Scanning
+ready scan                             # Score + blocking items
+ready scan --verbose                   # Full detail — all checks, evidence, fix hints
+ready scan --calibrate                 # Report-only (no exit code failure)
+ready scan --json                      # Machine-readable output
+ready scan --baseline FILE             # Write baseline snapshot (enables drift tracking)
+ready scan --suggest-tuning            # Show pattern tuning suggestions after scan
+
+# Setup
+ready init                             # Scaffold .readiness/ with starter pack
+ready init --pack web-api              # Scaffold with a specific pack
+ready init --list-packs                # List available packs
+
+# Authoring & inference
+ready infer                            # Analyze codebase → propose tailored checkpoints (human approves each)
+ready author --from FILE               # Generate AI prompt from a guideline document
+
+# Audit trail
+ready badge                            # Generate README badge from current score
+ready decisions                        # Show all active, expiring, and expired exceptions
+ready history [BASELINES...]           # Show readiness trend from baseline snapshots
+ready audit                            # Audit exception health, definition staleness, and score health
+
+# Work items
+ready items --create                   # Propose + create work items (human approves each)
+ready items --verify                   # Cross-check work items vs code
+
+# Cross-repo
+ready aggregate PATHS...               # Cross-repo heatmap from multiple baselines
+ready aggregate PATHS... --html        # Generate self-contained HTML heatmap report
+```
+
+## AI Integration
+
+ready ships a [Model Context Protocol](https://modelcontextprotocol.io) server (`ready-mcp`) so any MCP client — Claude, Cursor, Copilot — can run scans and inspect checkpoints directly.
+
+```bash
+pip install "readiness-as-code[mcp]"
+ready-mcp
+```
+
+| Tool | Description |
+|------|-------------|
+| `scan_repo` | Full readiness scan with results |
+| `list_checkpoints` | View all checkpoint definitions |
+| `explain_checkpoint` | Deep-dive on a specific check |
+| `aggregate_baselines` | Cross-repo heatmap for systemic gap detection |
+
+For prompt-based authoring with any model:
+
+```bash
+ready author --from docs/ops-review.md   # generates author-prompt.md, paste into any AI
+```
+
+**→ [MCP setup for Claude Desktop, Cursor, VS Code](mcp/README.md)**
+
+## Design Principles
+
+These principles define what *readiness as code* means in practice. They are not implementation choices — they are the practice itself.
+
+1. **Detection, not decisions.** The scanner finds gaps. Humans decide what to do.
+2. **Continuous, not ceremonial.** Checked on every PR, not once a quarter.
+3. **Velocity-aware, not velocity-hostile.** Designed to run at the speed of AI-assisted development — no human bottleneck in the loop.
+4. **Portable, not hosted.** Files in your repo. No infrastructure.
+5. **Evidence-backed, not trust-based.** Every assertion has a file path, attestation, or work item.
+6. **Expiring, not permanent.** Accepted risks have expiry dates. Nothing is forever.
+7. **Score-first, not report-first.** The answer to "are we ready?" is one line. Detail is on demand.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE)

readiness_as_code-0.7.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+readiness_as_code-0.7.0.dist-info/licenses/LICENSE,sha256=E4kPWhAHNj0N_P0mcA_JARQCIu92VsuJQ9ThV5vrd0o,1073
+ready/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ready/__main__.py,sha256=3ptnlLI5lhgJA96Gp-kv6_3xTbRZaQwp_kWNQB1vxEA,68
+ready/engine.py,sha256=tJ5cchXYhq8DKb13fZC9GArfDVO58ybKZj-m1Lcdsj0,14916
+ready/mcp_server.py,sha256=T0rXuf5VyoiSXv-pe3KXJQoOk-gGuMyv7mYFEwkvNhQ,11146
+ready/ready.py,sha256=HKTdEnO4JsiebZK24EL49q7Tpt9FO0rInoRJw_610tM,113708
+ready/validators.py,sha256=7PYvZvzadbQ04IojixpbivcDiRmf8rGBV2YPoSg557s,1241
+ready/watch.py,sha256=lD2bcCEB18FmbHjfef7DDnnH6A66uBQXiIpUMtKcc3Y,9270
+ready/adapters/__init__.py,sha256=4T0mxm9Ho70UuPhgLWNaqWR5gILvgaxmhStYVBA_Nr8,1488
+ready/adapters/ado.py,sha256=MZbR6AgXj-p-jkMGjpLZzLxJwCpf8cENDoZYimvdtog,6477
+ready/adapters/github_issues.py,sha256=qYLj1cuUwK7suh6vGFdL2GmsW7EFt28S6BNAIUcZfiI,5382
+ready/adapters/jira.py,sha256=8e7mMOcHp8IfYYQiSUFtjbTtOIUfWPj1tXF6B2R50vQ,10523
+ready/examples/engineering-review/checkpoint-definitions.json,sha256=Rihp_KbVIiXcpSQbiQjdmrneWv-YD6-mw05l98m8EBs,20433
+ready/examples/governance/checkpoint-definitions.json,sha256=IMIcd8rB662DLSyNbsI2s5FAQfE5vpSu59NfvJih2bM,11420
+ready/examples/operational-review/checkpoint-definitions.json,sha256=cM6Vl4U3YtLgPbMJtqSVak2zh0j3DtqjBlcz3PkZYxs,10793
+ready/examples/security-baseline/checkpoint-definitions.json,sha256=Y7YMEET4rPCRroYk58Q3eBS3U5s0azBHOKORq98PuxY,7901
+ready/examples/service-migration/checkpoint-definitions.json,sha256=C5I0oqmhmxg6LloaUpMNeNJuxFjxKTXNJuJonvcAsxg,7506
+ready/examples/starter-pack/checkpoint-definitions.json,sha256=VY8exptIN84jN3L9fW3Awf2jo_U7NY79UnXXMNUZp-g,8884
+ready/examples/starter-pack/exceptions.json,sha256=QMuE-XJFXaztARMzVaVMrrk9TlWNbcbeqMe2dJQU764,43
+ready/examples/starter-pack/external-evidence.json,sha256=zi6Akhc2l0zvtOfS5uko2jvMPzPYr-SB1OINbXVQJjM,45
+ready/examples/telemetry/checkpoint-definitions.json,sha256=mELRe15GYMmE1KeBNUdGHIkGBXikcFDpgnoQoVhb1yM,7840
+ready/examples/web-api/README.md,sha256=G9FbBzON0hBMdDJKDjoPqvIcSqw4G9ZKrDaqvVmeKas,1262
+ready/examples/web-api/checkpoint-definitions.json,sha256=e0Pth930uPCwghV0PfsbOT41Ws6ljs9lfcQrFs5VqXQ,14036
+ready/formatters/__init__.py,sha256=aehkxsKbVE57uQB2Q2hbw3GR_ysCOTPHnhmMcTtmJCc,199
+ready/formatters/json_formatter.py,sha256=TPClaNznx1O2Y6qaQuhVQKio0RpOFAn0NKZ-UfXbpe8,249
+ready/formatters/markdown.py,sha256=297CSFtNL0lJDhIItYd6FOhzl03PCAz_jm-X-X58aJo,6215
+ready/formatters/terminal.py,sha256=gXg0GpXtXpnatxGC9pBv3wof5siaSFjAtu67sE8N-2E,6951
+ready/plugins/__init__.py,sha256=OEjJELtk4RLU5fLgv-uVV6Ol-fDzCkCH4WmePpwedRQ,297
+ready/plugins/base.py,sha256=i1j1-HlLEyMepP0_Z3mbXFmoDqk5qfDoU6tn9I5eihc,1689
+ready/plugins/external_plugin.py,sha256=YUaAaPmkefDdWZJSh32ex18T6J4OJPi9qLlPxCc7Goc,1755
+ready/plugins/file_count_plugin.py,sha256=Qzb47S5d4vf9zYBXLoCCy_pRxI5RFyrS1cdOBxxAxvc,556
+ready/plugins/file_exists_plugin.py,sha256=1wwKcxWWY6zkS4BthKdfZy2_s14boXeJi7QOJlDB11I,728
+ready/plugins/glob_plugin.py,sha256=UAOYzpQssHsCcN2wZtr_GIdwYjtUo-vIlo8y6vF-ckg,1686
+ready/plugins/grep_plugin.py,sha256=zIpA9YoaWkcS15iKiK2tu3JSM0YmmoUzoiiwM-lz5uI,2560
+ready/plugins/hybrid_plugin.py,sha256=CD3fipyguSUuYDfmIO_cMyvWl5WbuNukt_w0LbqG5_A,2934
+ready/plugins/json_path_plugin.py,sha256=Tx2nmUX25jEtTttVEnNEjHCnCqynxZe7BvXVRH46uD8,2017
+ready/plugins/registry.py,sha256=S8AR7eVZ59kiDzRUUmj2JZq8ktSMeIwKHgW8suCYpdk,2062
+ready/plugins/utils.py,sha256=eddbB6elBm-ukQ7IIn1QS-k-ZPvai4jTMZLjJFfV1MI,3273
+readiness_as_code-0.7.0.dist-info/METADATA,sha256=d30PPzzATyRf1cdMf-VLZBZXJYjYa_ogzevE5Dit88Q,13298
+readiness_as_code-0.7.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+readiness_as_code-0.7.0.dist-info/entry_points.txt,sha256=85h9s35y4PzxPjUOqq2oNbVsmfiT06A-oV4zKwlKQBI,77
+readiness_as_code-0.7.0.dist-info/top_level.txt,sha256=7RpUW7heVYFrv5VmsCiyoLxFa4j0n28mbAQBBIgkGUs,6
+readiness_as_code-0.7.0.dist-info/RECORD,,

readiness_as_code-0.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

readiness_as_code-0.7.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+ready = ready.ready:main
+ready-mcp = ready.mcp_server:main

readiness_as_code-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremiah Walters
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

readiness_as_code-0.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ready

ready/__main__.py

@@ -0,0 +1,4 @@
+from ready.ready import main
+
+if __name__ == "__main__":
+    main()

ready/adapters/__init__.py

@@ -0,0 +1,61 @@
+"""
+Abstract work item adapter interface.
+
+Implement this to integrate with your project tracker.
+Ships with GitHub Issues and Azure DevOps adapters.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class WorkItemDraft:
+    checkpoint_id: str
+    title: str
+    description: str
+    severity: str
+    evidence: list[str]
+    fix_hint: str
+    doc_link: str
+    guideline: str
+    guideline_section: str
+    labels: list[str]
+
+
+@dataclass
+class WorkItemResult:
+    id: str
+    url: str
+    status: str
+    checkpoint_id: str
+
+
+class WorkItemAdapter(ABC):
+    """Interface for work item integrations."""
+
+    @abstractmethod
+    def create_draft(self, draft: WorkItemDraft) -> WorkItemResult:
+        """Create a work item from a draft. Returns the created item."""
+        ...
+
+    @abstractmethod
+    def get_status(self, item_id: str) -> Optional[WorkItemResult]:
+        """Get the current status of a work item."""
+        ...
+
+    @abstractmethod
+    def list_open(self, label: str | None = None) -> list[WorkItemResult]:
+        """List open work items, optionally filtered by label."""
+        ...
+
+    @abstractmethod
+    def close(self, item_id: str, reason: str = "Resolved by scan") -> bool:
+        """Close a work item."""
+        ...
+
+    @abstractmethod
+    def reopen(self, item_id: str, reason: str = "Regression detected by scan") -> bool:
+        """Reopen a previously closed work item."""
+        ...

ready/adapters/ado.py

@@ -0,0 +1,174 @@
+"""
+Azure DevOps adapter for ready work item tracking.
+
+Requires: AZURE_DEVOPS_PAT and AZURE_DEVOPS_ORG environment variables.
+"""
+
+import json
+import os
+import base64
+import urllib.request
+import urllib.error
+from typing import Optional
+
+from . import WorkItemAdapter, WorkItemDraft, WorkItemResult
+
+
+class AzureDevOpsAdapter(WorkItemAdapter):
+    """Create and track readiness gaps as Azure DevOps work items (PBIs/Bugs)."""
+
+    def __init__(
+        self,
+        org: str | None = None,
+        project: str | None = None,
+        pat: str | None = None,
+        work_item_type: str = "Product Backlog Item",
+    ):
+        self.org = org or os.environ.get("AZURE_DEVOPS_ORG", "")
+        self.project = project or os.environ.get("AZURE_DEVOPS_PROJECT", "")
+        self.pat = pat or os.environ.get("AZURE_DEVOPS_PAT", "")
+        self.work_item_type = work_item_type
+        self.api_base = f"https://dev.azure.com/{self.org}/{self.project}/_apis"
+
+        if not self.org or not self.project:
+            raise ValueError(
+                "Azure DevOps org and project required. "
+                "Set AZURE_DEVOPS_ORG and AZURE_DEVOPS_PROJECT env vars."
+            )
+
+    def _headers(self) -> dict:
+        creds = base64.b64encode(f":{self.pat}".encode()).decode()
+        return {
+            "Content-Type": "application/json-patch+json",
+            "Authorization": f"Basic {creds}",
+        }
+
+    def _request(self, method: str, path: str, data=None) -> dict:
+        url = f"{self.api_base}{path}"
+        if "?" in url:
+            url += "&api-version=7.1"
+        else:
+            url += "?api-version=7.1"
+
+        body = json.dumps(data).encode("utf-8") if data else None
+        req = urllib.request.Request(
+            url, data=body, headers=self._headers(), method=method
+        )
+        try:
+            with urllib.request.urlopen(req) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = e.read().decode("utf-8") if e.fp else ""
+            raise RuntimeError(f"ADO API error {e.code}: {error_body}") from e
+
+    def create_draft(self, draft: WorkItemDraft) -> WorkItemResult:
+        description = (
+            f"<b>Checkpoint:</b> {draft.checkpoint_id}<br>"
+            f"<b>Severity:</b> {draft.severity.upper()}<br>"
+            f"<b>Guideline:</b> {draft.guideline} — {draft.guideline_section}<br><br>"
+            f"{draft.description}<br><br>"
+            f"<b>Evidence:</b><ul>{''.join(f'<li>{e}</li>' for e in draft.evidence)}</ul>"
+            f"<b>Fix:</b> {draft.fix_hint}"
+        )
+        if draft.doc_link:
+            description += f'<br><br><a href="{draft.doc_link}">Documentation</a>'
+
+        patch_doc = [
+            {"op": "add", "path": "/fields/System.Title", "value": f"[{draft.severity.upper()}] {draft.title}"},
+            {"op": "add", "path": "/fields/System.Description", "value": description},
+            {"op": "add", "path": "/fields/System.Tags", "value": f"readiness-gap; {draft.checkpoint_id}; severity:{draft.severity}"},
+        ]
+
+        result = self._request(
+            "POST",
+            f"/wit/workitems/${self.work_item_type}",
+            patch_doc,
+        )
+
+        wi_id = str(result["id"])
+        url = result.get("_links", {}).get("html", {}).get("href", "")
+
+        return WorkItemResult(
+            id=wi_id,
+            url=url,
+            status=result.get("fields", {}).get("System.State", "New"),
+            checkpoint_id=draft.checkpoint_id,
+        )
+
+    def get_status(self, item_id: str) -> Optional[WorkItemResult]:
+        try:
+            result = self._request("GET", f"/wit/workitems/{item_id}")
+            fields = result.get("fields", {})
+            tags = fields.get("System.Tags", "")
+            cp_id = ""
+            for tag in tags.split(";"):
+                tag = tag.strip()
+                if tag.startswith("cp:") or (len(tag) > 3 and "-" in tag and tag[0].isalpha()):
+                    cp_id = tag
+                    break
+
+            return WorkItemResult(
+                id=str(result["id"]),
+                url=result.get("_links", {}).get("html", {}).get("href", ""),
+                status=fields.get("System.State", "Unknown"),
+                checkpoint_id=cp_id,
+            )
+        except RuntimeError:
+            return None
+
+    def list_open(self, label: str | None = None) -> list[WorkItemResult]:
+        tag_filter = "readiness-gap"
+        if label:
+            tag_filter += f" AND {label}"
+
+        wiql = {
+            "query": (
+                f"SELECT [System.Id] FROM WorkItems "
+                f"WHERE [System.Tags] CONTAINS '{tag_filter}' "
+                f"AND [System.State] <> 'Closed' AND [System.State] <> 'Done' "
+                f"ORDER BY [System.CreatedDate] DESC"
+            )
+        }
+
+        # WIQL uses regular JSON content type
+        url = f"{self.api_base}/wit/wiql?api-version=7.1"
+        body = json.dumps(wiql).encode("utf-8")
+        headers = self._headers()
+        headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+
+        try:
+            with urllib.request.urlopen(req) as resp:
+                data = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError:
+            return []
+
+        items = []
+        for wi in data.get("workItems", []):
+            status = self.get_status(str(wi["id"]))
+            if status:
+                items.append(status)
+
+        return items
+
+    def close(self, item_id: str, reason: str = "Resolved by scan") -> bool:
+        try:
+            patch_doc = [
+                {"op": "add", "path": "/fields/System.State", "value": "Closed"},
+                {"op": "add", "path": "/fields/System.History", "value": reason},
+            ]
+            self._request("PATCH", f"/wit/workitems/{item_id}", patch_doc)
+            return True
+        except RuntimeError:
+            return False
+
+    def reopen(self, item_id: str, reason: str = "Regression detected by scan") -> bool:
+        try:
+            patch_doc = [
+                {"op": "add", "path": "/fields/System.State", "value": "New"},
+                {"op": "add", "path": "/fields/System.History", "value": reason},
+            ]
+            self._request("PATCH", f"/wit/workitems/{item_id}", patch_doc)
+            return True
+        except RuntimeError:
+            return False