chore: archive v1.9 milestone

Author: arkadyb

.github/workflows/release.yml

@@ -0,0 +1,79 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and build tooling
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install ".[dev]" build
+
+      - name: Run tests
+        run: python -m pytest
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Upload release artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/*
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    environment: testpypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.planning/MILESTONES.md

@@ -1,5 +1,23 @@
 # Milestones
 
+## v1.9 PyPI Distribution and Release Readiness (Shipped: 2026-05-15)
+
+**Phases completed:** 4 phases, 11 plans, 27 tasks
+
+**Key accomplishments:**
+
+- PyPI metadata now uses Hatchling dynamic versioning, with tests enforcing the single-source version contract and the required discoverability fields.
+- Source and wheel artifacts now include the release files we need, and the package test suite verifies the built outputs when they exist.
+- README installation instructions now lead with PyPI commands, and the built artifacts pass `twine check` with the new long-description content.
+- A gated venv-based harness now proves the built wheel installs cleanly without optional dependencies and keeps the install tests opt-in for normal runs.
+- The built wheel now installs all declared extras in isolated venvs, and the Qdrant wrapper surface resolves from the `corpulse[qdrant]` extra.
+- Optional dependency failures now tell users exactly what to install, and the full phase verification suite passes against the rebuilt wheel.
+- Exact post-publish PyPI smoke checks for `corpulse` and `corpulse[qdrant]`, with tests pinning the release checklist wording
+
+**Known deferred items at close:** 3 old quick-task placeholders already tracked in `.planning/STATE.md`.
+
+---
+
 ## v1.8 Workload Observability and Replay Feasibility (Shipped: 2026-05-05)
 
 **Phases completed:** 6 phases, 21 plans, 61 tasks

.planning/PROJECT.md

@@ -8,16 +8,22 @@ A Python library that tracks and analyzes RAG corpus health for RAG teams. It de
 
 RAG teams can point corpulse at their vector DB and immediately understand what's wrong with their corpus without manual audits.
 
-## Completed Milestone: v1.8 Workload Observability and Replay Feasibility
+## Completed Milestone: v1.9 PyPI Distribution and Release Readiness
 
-**Goal:** Research and, where feasible, implement a first-class workload observability layer that extends corpulse from corpus health into RAG request traces, serving diagnostics, session analytics, and replay-ready exports.
+**Goal:** Make corpulse installable from PyPI with verified optional extras and a repeatable release path.
 
 **Target features:**
-- Feasibility research for RAG workload trace schema, storage implications, and replay boundaries
-- Structured `log_rag_request()` / `alog_rag_request()` APIs with sessions, prompt components, token counts, timings, errors, and content hashes
-- JSONL import/export for privacy-preserving workload traces
-- Workload, latency, and session reports that summarize traffic shape and serving behavior
-- Dependency-free callable replay proof on top of captured/imported traces; endpoint adapters and benchmark export remain future work
+- PyPI-ready package metadata, README rendering, package contents, license inclusion, and version consistency
+- Verified install surfaces for `pip install corpulse`, `pip install corpulse[qdrant]`, and existing optional extras
+- GitHub Actions release automation using PyPI Trusted Publishing for TestPyPI and PyPI
+- Documentation updated from GitHub install syntax to PyPI install syntax
+- Release checklist covering build artifacts, clean-environment installs, imports, extras, and Qdrant wrapper availability
+
+## Current Milestone
+
+None. Start the next milestone with `$gsd-new-milestone`.
+
+The next milestone should start from fresh requirements. Candidate directions include release-note maturity, signed artifacts, PyPI adoption reporting, or the next integration adapter.
 
 ## Requirements
 
@@ -67,12 +73,16 @@ RAG teams can point corpulse at their vector DB and immediately understand what'
 - ✓ Workload and serving reports over captured/imported traces — Phase 30
 - ✓ Session analytics and repeated-context reuse signals — Phase 31
 - ✓ Replay feasibility and dependency-free callable replay proof — Phase 32
+- ✓ PyPI-ready package metadata, README rendering, package contents, license inclusion, and version consistency — v1.9
+- ✓ Verified install surfaces for `pip install corpulse`, `pip install corpulse[qdrant]`, and existing optional extras — v1.9
+- ✓ GitHub Actions release automation using PyPI Trusted Publishing for TestPyPI and PyPI — v1.9
+- ✓ PyPI-first installation documentation and release checklist with post-publish smoke checks — v1.9
 
 ### Active
 
 <!-- Current scope. Building toward these. -->
 
-- [ ] Define the next milestone with fresh requirements and roadmap.
+(None. Define fresh requirements with `$gsd-new-milestone`.)
 
 ### Out of Scope
 
@@ -83,7 +93,6 @@ RAG teams can point corpulse at their vector DB and immediately understand what'
 - LangChain/LlamaIndex plugin — future milestone after wrapper pattern is proven
 - Standalone audit mode (crawl vector DB without runtime) — future milestone
 - CLI tool — future milestone
-- PyPI publishing — distributing via GitHub only for now
 - Web dashboard / UI — keep it library-first
 - **Faithfulness / Hallucination Rate** — requires LLM-as-judge to verify generated answer against retrieved context; not measurable from retrieval logs alone; use Ragas or TruLens for generation-layer evaluation
 - **Context Precision** — requires ground-truth relevance labels per query; corpulse has no label store and no annotation workflow; belongs in offline eval frameworks
@@ -92,17 +101,23 @@ RAG teams can point corpulse at their vector DB and immediately understand what'
 
 ## Current State
 
+corpulse completed milestone `v1.9`, moving distribution readiness from GitHub-only installs to a PyPI-first release posture. The package metadata, source distribution, wheel contents, optional extras, release workflow, Trusted Publishing documentation, and install docs are now covered by static tests, build checks, and milestone verification artifacts.
+
+The release workflow builds once, uploads the tested `dist/*` artifacts, publishes to TestPyPI on manual dispatch, and publishes to PyPI only from `v*` tags through OIDC Trusted Publishing. The production `pypi` GitHub environment approval gate and the live TestPyPI/PyPI smoke checks remain explicit manual release-time actions documented in `.github/RELEASE_CHECKLIST.md`.
+
 corpulse completed milestone `v1.7`, adding a shared generic wrapping engine and migrating the Qdrant compatibility wrappers onto that architecture. The library now supports a documented advanced adapter path for future integrations while preserving lazy optional dependency behavior and Qdrant compatibility.
 
 The shipped `v1.8` milestone was seeded by `.planning/research/RAGPULSE-COMPARISON-FEATURES.md`, which found that RAGPulse is most useful as a workload trace and replay reference rather than as a corpus-health competitor. corpulse kept its corpus-health core while adding an optional workload/serving layer for request composition, traffic shape, latency, sessions, and replayable exports.
 
 Phase 27 completed the feasibility decision record and locked the MVP direction on an append-only request-trace schema. Phases 28-31 delivered trace capture, JSONL import/export, workload and serving reports, and session analytics with repeated-context reuse signals. Phase 32 validated that callable replay is feasible and delivered dependency-free sync/async replay helpers. v1.8 shipped on 2026-05-05. It did not add a built-in OpenAI endpoint client; richer benchmark export and endpoint adapters remain future work.
 
+The v1.9 milestone moved distribution from GitHub-only to PyPI-ready. `pyproject.toml` uses Hatchling dynamic versioning, optional extras are verified from built artifacts, README is PyPI-first, and `.github/workflows/release.yml` implements the Trusted Publishing release path.
+
 ## Next Milestone Goals
 
-- Start the next milestone with fresh requirements instead of extending v1.8 in place.
-- Keep future replay optional and dependency-light; avoid turning corpulse into a full evaluation framework or dashboard.
-- Consider future endpoint adapters and benchmark export only after the callable replay proof has real adopter feedback.
+- Define fresh requirements before starting implementation.
+- Consider release maturity: release notes, signed artifacts, and PyPI adoption reporting.
+- Consider the next integration adapter now that generic wrapping and distribution readiness are in place.
 
 <details>
 <summary>Archived v1.7 milestone framing</summary>
@@ -184,7 +199,7 @@ Make the persistence layer pluggable so corpulse can use PostgreSQL in productio
 
 - **Tech stack**: Python, SQLite for local persistence, PostgreSQL as the production backend target
 - **Dependencies**: numpy and scikit-learn are hard dependencies; pandas and tabulate remain optional; psycopg and asyncpg are optional extras
-- **Distribution**: GitHub-only for v1.x; no PyPI publishing yet
+- **Distribution**: v1.9 targets PyPI publication with GitHub source install kept as a fallback path
 - **Vector DB**: Qdrant remains the first wrapper target
 - **Compatibility**: Python 3.10+
 - **Backwards compat**: `Corpulse()` with no args must still work exactly as before
@@ -197,12 +212,14 @@ Make the persistence layer pluggable so corpulse can use PostgreSQL in productio
 | Decision | Rationale | Outcome |
 |----------|-----------|---------|
 | Qdrant as first wrapper | Growing production adoption in RAG pipelines; good Python client | Shipped |
-| GitHub-only distribution | Keep overhead low for v1; PyPI later when stable | Pending |
+| GitHub-only distribution | Keep overhead low before the first public package release | Superseded by v1.9 |
 | Wrapper-first over audit-first | Query-dependent features are the most actionable; wrapper enables them automatically | Shipped |
 | Keep manual API alongside wrapper | Existing API still useful for custom integrations; wrapper is additive | Shipped |
 | Pluggable backend interface | Service repo needs Postgres; library should support multiple backends | Shipped in v1.1 |
 | Explicit backend config over connection strings | More flexible and clearer than implicit string configuration | Shipped in v1.1 |
 | Narrow async facade for v1.1 | Async service integration was needed now; full async analytics parity was not yet justified | Shipped in v1.1 |
+| PyPI Trusted Publishing over API tokens | Avoid long-lived publishing credentials and keep release automation auditable | Shipped in v1.9 |
+| PyPI-first install docs with GitHub source fallback | PyPI is the user path; source install remains useful for unreleased fixes | Shipped in v1.9 |
 | Evidence-gated requirement closure | Milestone claims should match recorded verification, not just landed code | Shipped in v1.1 |
 | Structured-payload async reports | Avoids coupling `AsyncCorpulse` to stdout and keeps output consumable by services/tests; sync `report`/`cleanup_report` become a thin formatter over the same payload | Shipped in Phase 12 |
 | Pandas stays optional on async path | Keeps install footprint small for async service users who don't need DataFrames; mirrors sync behavior | Shipped in Phase 12 |
@@ -214,6 +231,7 @@ Make the persistence layer pluggable so corpulse can use PostgreSQL in productio
 | Qdrant remains first-class while the generic API serves advanced adapter authors | Keeps the common path simple for existing users while making future integrations cheaper to build | Shipped in v1.7 |
 | Workload observability is the v1.8 priority over a second vector DB adapter | RAGPulse comparison showed the bigger product gap is production request behavior, not another retrieval-client wrapper | Shipped through Phase 31 |
 | Callable replay over built-in endpoint replay | Current traces do not guarantee canonical messages, raw component content, tool payloads, streamed chunks, or response bodies; user callables can bridge private endpoint-specific payloads without new core dependencies | Shipped in Phase 32 |
+| PyPI Trusted Publishing over long-lived release tokens | OIDC avoids storing a long-lived PyPI API token in GitHub secrets and gives PyPI a verifiable source repository link | Pending in v1.9 |
 
 ## Evolution
 
@@ -233,4 +251,4 @@ This document evolves at phase transitions and milestone boundaries.
 4. Update Context with current state
 
 ---
-*Last updated: 2026-05-05 after Phase 32 execution*
+*Last updated: 2026-05-15 after starting milestone v1.9*

.planning/ROADMAP.md

@@ -11,97 +11,26 @@
 - ✅ **v1.6 — Generation Trace Capture** — completed 2026-04-20, archive: `.planning/milestones/v1.6-ROADMAP.md`
 - ✅ **v1.7 — Generic Integration Wrapping** — Phases 25-26 (completed 2026-04-22, archive: `.planning/milestones/v1.7-ROADMAP.md`)
 - ✅ **v1.8 — Workload Observability and Replay Feasibility** — Phases 27-32 (shipped 2026-05-05, archive: `.planning/milestones/v1.8-ROADMAP.md`)
-- ◆ **v1.9 — PyPI Distribution and Release Readiness** — Phases 33-36 (active)
+- ✅ **v1.9 — PyPI Distribution and Release Readiness** — Phases 33-36 (shipped 2026-05-15, archive: `.planning/milestones/v1.9-ROADMAP.md`)
 
 ## Current Status
 
-- Latest shipped milestone: `v1.8 — Workload Observability and Replay Feasibility`
-- Active milestone: `v1.9 — PyPI Distribution and Release Readiness`
-- Next workflow step: `$gsd-execute-phase 35`
+- Latest shipped milestone: `v1.9 — PyPI Distribution and Release Readiness`
+- Active milestone: none
+- Next workflow step: `$gsd-new-milestone`
 
-## Phases
+## Archived Milestone Details
 
-### Phase 33: Package Metadata and Build Readiness
+Full shipped milestone roadmaps are archived under `.planning/milestones/`.
 
-**Goal:** Make the package metadata, README, versioning, and build artifacts ready for PyPI.
-
-**Requirements:** PKG-01, PKG-02, PKG-03
-
-**Success Criteria:**
-1. `pyproject.toml` contains PyPI-ready metadata, URLs, classifiers, and license-file configuration.
-2. Runtime version and package metadata version have a single-source or verified consistency path.
-3. `python -m build` produces an sdist and wheel containing the intended package files, README, and license.
-4. Package metadata and README render cleanly for PyPI.
-
-### Phase 34: Optional Extras Install Verification
-
-**Goal:** Prove base and optional-extra installs behave correctly from built artifacts without bloating the core install.
-
-**Requirements:** PKG-04, EXTRA-01, EXTRA-02, EXTRA-03, EXTRA-04
-
-**Success Criteria:**
-1. A clean environment can install the base artifact and import `corpulse` without optional dependencies.
-2. A clean environment can install `corpulse[qdrant]` from the built artifact and import/instantiate the Qdrant wrapper surface.
-3. Existing optional extras install cleanly or have documented constraints.
-4. Optional integration failures produce actionable `pip install corpulse[...]` guidance.
-
-### Phase 35: Trusted Publishing Release Automation
-
-**Goal:** Add GitHub Actions release automation that builds once and publishes through PyPI Trusted Publishing.
-
-**Requirements:** REL-01, REL-02, REL-03, REL-04
-
-**Success Criteria:**
-1. CI builds and stores source and wheel artifacts after tests pass.
-2. TestPyPI publishing uses `pypa/gh-action-pypi-publish@release/v1` with OIDC Trusted Publishing.
-3. PyPI publishing is tag-gated and uses OIDC Trusted Publishing, not a long-lived PyPI token.
-4. The PyPI publish job uses a protected environment or equivalent explicit release gate.
-
-### Phase 36: User Install Docs and Release Validation
-
-**Goal:** Make PyPI install instructions the user-facing path and validate the first release end to end.
-
-**Requirements:** DOC-01, DOC-02, DOC-03, VAL-01, VAL-02
-
-**Success Criteria:**
-1. README/docs show `pip install corpulse` as the primary installation command.
-2. README/docs show `pip install corpulse[qdrant]` as the primary Qdrant integration command.
-3. Release checklist documents version bump, build, TestPyPI validation, PyPI publish, and post-publish smoke checks.
-4. Published PyPI package installs in a clean environment.
-5. Published `corpulse[qdrant]` extra installs in a clean environment and exposes the Qdrant wrapper surface.
-
-## Progress
-
-| Phase | Milestone | Plans Complete | Status | Completed |
-| --- | --- | --- | --- | --- |
-| 33. Package Metadata and Build Readiness | v1.9 | 3/3 | Complete | 2026-05-15 |
-| 34. Optional Extras Install Verification | v1.9 | 3/3 | Complete | 2026-05-15 |
-| 35. Trusted Publishing Release Automation | v1.9 | 0/0 | Not Started | — |
-| 36. User Install Docs and Release Validation | v1.9 | 0/0 | Not Started | — |
-
-## Coverage
-
-v1.9 maps 17/17 requirements to phases in `.planning/REQUIREMENTS.md`.
-
-| Requirement | Phase |
-|-------------|-------|
-| PKG-01 | Phase 33 |
-| PKG-02 | Phase 33 |
-| PKG-03 | Phase 33 |
-| PKG-04 | Phase 34 |
-| EXTRA-01 | Phase 34 |
-| EXTRA-02 | Phase 34 |
-| EXTRA-03 | Phase 34 |
-| EXTRA-04 | Phase 34 |
-| REL-01 | Phase 35 |
-| REL-02 | Phase 35 |
-| REL-03 | Phase 35 |
-| REL-04 | Phase 35 |
-| DOC-01 | Phase 36 |
-| DOC-02 | Phase 36 |
-| DOC-03 | Phase 36 |
-| VAL-01 | Phase 36 |
-| VAL-02 | Phase 36 |
+| Milestone | Archive |
+|-----------|---------|
+| v1.1 | `.planning/milestones/v1.1-ROADMAP.md` |
+| v1.2 | `.planning/milestones/v1.2-ROADMAP.md` |
+| v1.6 | `.planning/milestones/v1.6-ROADMAP.md` |
+| v1.7 | `.planning/milestones/v1.7-ROADMAP.md` |
+| v1.8 | `.planning/milestones/v1.8-ROADMAP.md` |
+| v1.9 | `.planning/milestones/v1.9-ROADMAP.md` |
 
 ---
-*Last updated: 2026-05-15 after milestone v1.9 roadmap creation*
+*Last updated: 2026-05-15 after v1.9 milestone completion*