cohorte-engine 1.0.0a1__tar.gz

cohorte_engine-1.0.0a1/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+      - run: uv run pytest
+      - run: uv build
+      - run: uv run python tests/packaging/verify_clean_install.py
+      - run: uv run python tests/packaging/verify_upgrade.py

cohorte_engine-1.0.0a1/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release Python Cohorte
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: python-release
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  metadata:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - name: Require main branch
+        env:
+          RELEASE_REF: ${{ github.ref }}
+        run: test "$RELEASE_REF" = refs/heads/main
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+          enable-cache: false
+      - name: Validate version and release notes
+        run: python scripts/release_meta.py check
+      - id: version
+        run: echo "version=$(python scripts/release_meta.py version)" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: metadata
+    uses: ./.github/workflows/ci.yml
+
+  publish:
+    needs: [metadata, ci]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    outputs:
+      release_url: ${{ steps.release.outputs.url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+      - name: Build and verify clean installation
+        run: |
+          uv build --no-sources
+          uv run python tests/packaging/verify_clean_install.py
+      - name: Publish wheel and source archive to PyPI
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/
+      - name: Create GitHub prerelease with changelog and artifacts
+        id: release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.metadata.outputs.version }}
+        run: |
+          python scripts/release_meta.py notes --output release-notes.md
+          TAG="python-v${VERSION}"
+          if ! gh release view "$TAG" >/dev/null 2>&1; then
+            if [[ "$VERSION" == *a* || "$VERSION" == *b* || "$VERSION" == *rc* ]]; then
+              gh release create "$TAG" dist/* --target "$GITHUB_SHA" --title "Cohorte $VERSION" --notes-file release-notes.md --prerelease
+            else
+              gh release create "$TAG" dist/* --target "$GITHUB_SHA" --title "Cohorte $VERSION" --notes-file release-notes.md
+            fi
+          fi
+          echo "url=$(gh release view "$TAG" --json url --jq .url)" >> "$GITHUB_OUTPUT"
+
+  discord:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+          enable-cache: false
+      - name: Post changelog to the Cohorte Discord thread
+        env:
+          DISCORD_FORUM_WEBHOOK: ${{ secrets.DISCORD_FORUM_WEBHOOK }}
+          DISCORD_THREAD_ID: ${{ secrets.DISCORD_THREAD_ID }}
+          RELEASE_URL: ${{ needs.publish.outputs.release_url }}
+        run: python scripts/release_meta.py discord --release-url "$RELEASE_URL"

cohorte_engine-1.0.0a1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.cohorte/

cohorte_engine-1.0.0a1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Release notes for the Python Cohorte package. Add a dated section for each published version,
+with the newest version first. Describe the verified scope and known limitations of a dev release.
+
+## Unreleased
+
+_No changes recorded yet._
+
+## 1.0.0a1 — 2026-09-23
+
+- First scoped preview of the Python Cohorte engine, published as `cohorte-engine` with the `cohorte` CLI. It is separate from the earlier npm package and its version series.
+- Add durable SQLite workflows, isolated worktrees, review and fix gates, Fleet scheduling, V2 import, and local `cohorte/1` JSON-RPC service with event replay and run controls.
+- Add official Codex and Claude SDK adapters, native login handoff, and common redacted turn, tool and usage events. Live provider evidence is currently bounded to the qualified Darwin arm64 accounts and runtimes.
+- Qualify wheel installation and upgrade checks in CI on Ubuntu, macOS and Windows with Python 3.12 and 3.13; GitHub and GitLab delivery have also been exercised on disposable repositories.
+- Scope limits: François's Python-service PR remains open, so real François UI integration is not yet certified. The two-provider model corpus and real-host qualification across all target platforms are not complete. This alpha is not a V2-parity or full-platform support claim.
+
+## 0.1.0a1 — unreleased
+
+- Start the Python 3.12 root rewrite with no dependency on former Cohorte implementations.
+- Add strict contracts, a pure reducer, SQLite persistence and immutable artifacts.
+- Add project discovery, readiness/auth gates, conflict-aware scheduling and controlled checks.
+- Add the CLI, JSON-RPC stdio bridge, event replay and operation deduplication.
+- Add Codex subscription inspection and an explicit read-only live verification probe.
+- Certify Codex 0.155.1 read-only enforcement, interruption and session resume on Darwin arm64.
+- Build and verify wheel/sdist packaging while keeping provider support explicitly uncertified.

cohorte_engine-1.0.0a1/LICENSE

@@ -0,0 +1,4 @@
+SPDX-License-Identifier: AGPL-3.0-only
+
+This project is licensed under the GNU Affero General Public License version 3 only.
+The complete license text is available at https://www.gnu.org/licenses/agpl-3.0.txt.

cohorte_engine-1.0.0a1/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: cohorte-engine
+Version: 1.0.0a1
+Summary: Local, evidence-driven orchestration for coding agents
+Author: Cohorte contributors
+License: AGPL-3.0-only
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: openai-codex==0.155.1
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pywin32>=312; sys_platform == 'win32'
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk==0.2.157; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.25; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Provides-Extra: graphify
+Requires-Dist: graphifyy[mcp]==0.9.66; extra == 'graphify'
+Provides-Extra: serena
+Requires-Dist: mcp==2.2.0; extra == 'serena'
+Description-Content-Type: text/markdown
+
+# Cohorte V3
+
+For Python dev releases, see [the release runbook](docs/RELEASING.md).
+
+Cohorte is a local, evidence-driven workflow engine for official coding-agent clients. This
+repository is a Python 3.12 rewrite built at the repository root. It does not depend on the former
+TypeScript/Pi implementations.
+
+The current pre-release provides the deterministic core, bounded feature and Patch
+workflows, and overlap-aware Fleet execution:
+strict contracts, a pure workflow reducer, SQLite persistence, immutable artifacts, project
+discovery, DAG validation, isolated Git worktrees, controlled checks, independent read-only review,
+a review/fix loop, a JSON-RPC stdio bridge, and a CLI. Codex authentication and live execution are
+capability-gated. A Claude Agent SDK adapter is available through the optional `claude` dependency
+and `agent_defaults.provider: claude`; a bounded single-surface Claude workflow has passed live
+build, checks and review on Darwin arm64.
+Passive `auth status claude` checks the native CLI without exposing credentials. An explicit
+`auth verify claude --live` probe is available after confirming the account to use.
+The connected native account passed the Claude SDK smoke, structured read, workspace edit,
+outside-write denial, a guarded read-only write denial, and CLI cancellation/pause/resume probes.
+G0 remains partial: the full login interaction and safe native session recovery inside a workflow
+are not yet qualified.
+Both adapters now persist common turn, tool and usage events for workflow runs. The event payloads
+contain provider, phase, access and bounded metadata, without prompts, responses, commands or file
+paths. SDK token accounting can differ, and Claude's reported cost is an estimate rather than a
+provider billing statement.
+
+```bash
+uv sync --all-extras
+uv run cohorte doctor
+uv run cohorte --json init /path/to/project
+uv run cohorte --json status
+uv run pytest
+```
+
+For external context, set `integrations.retrieval.provider` to `serena` or `graphify` in the
+project profile. Serena needs the installed `serena` MCP executable. Graphify-Labs needs the
+`graphify` optional extra and a prebuilt `<repo>/graphify-out/graph.json`; for a code-only graph,
+run `graphify extract <repo> --code-only --no-cluster --out <repo>` explicitly before retrieval.
+Both providers fail visibly when unavailable; file fallback requires
+`integrations.retrieval.fallback_to_files: true`. Figma design snapshots use a file or node URL in
+`integrations.design.source` and a locally supplied `FIGMA_ACCESS_TOKEN` with
+`file_content:read` scope. The token is never part of the profile. To verify a real Figma snapshot
+without printing its contents, run `python tests/live/verify_figma_snapshot.py --source <file-or-node-url>`
+in a shell where the token is already set, or enter it at the hidden prompt.
+
+Prepare a feature with independent product, architecture and QA sessions, then approve the exact
+completed spec before freezing it:
+
+```bash
+cohorte --json --data-dir /path/to/data brainstorm PROJECT_ID \
+  --feature-id safe-export --idea "Add a safe run export" \
+  --answer "Keep data local and require atomic output" \
+  --repo /path/to/project --output brief.json --live
+cohorte --json --data-dir /path/to/data spec-freeze-request draft.json \
+  --profile project.json --repo /path/to/project
+cohorte --json --data-dir /path/to/data approve REQUEST_ID
+cohorte --json --data-dir /path/to/data spec-freeze draft.json \
+  --profile project.json --repo /path/to/project \
+  --decision-id DECISION_ID --output frozen.json
+```
+
+The brainstorm keeps each native session reference, contribution and disagreement. Freeze rejects
+incomplete drafts and approvals for a different spec hash, profile, reference set or generated plan.
+
+Run the disposable Codex vertical with the included frozen example:
+
+```bash
+cohorte --json loop examples/g1/spec.json \
+  --profile examples/g1/profile.json \
+  --repo /path/to/disposable/repository \
+  --worktrees /tmp/cohorte-worktrees \
+  --run-id demo-1 \
+  --live
+```
+
+Run several frozen feature specs as an overlap-aware fleet:
+
+```bash
+cohorte --json fleet specs/feature-a.json specs/feature-b.json \
+  --profile project.json \
+  --repo /path/to/disposable/repository \
+  --worktrees /tmp/cohorte-fleet-worktrees \
+  --fleet-id release-train-1 \
+  --live
+```
+
+Fleet computes the cross-feature dependency graph, parallelizes disjoint features, serializes
+overlapping write sets, integrates each candidate in order and reruns its declared checks after the
+base changes.
+
+Capture a ticket, freeze a bounded patch, and run it with a pre-existing regression:
+
+```bash
+cohorte --json --data-dir /path/to/data intake PROJECT_ID --file ticket.txt
+cohorte --json --data-dir /path/to/data patch-spec \
+  --source-artifact-id SOURCE_ID --source-revision 1 \
+  --profile project.json --patch-id fix-total --title "Fix total" \
+  --reproduction "Run the regression test" --observed "It returns 6" \
+  --expected "It returns 5" --surface python --write-path calc.py \
+  --check regression --in-scope "Correct total" --rollback "Revert calc.py" \
+  --output patch.json
+cohorte --json --data-dir /path/to/data patch patch.json \
+  --profile project.json --repo /path/to/repository \
+  --worktrees /tmp/cohorte-patch-worktrees --run-id patch-1 --live
+```
+
+Patch refuses to build unless every declared automatic regression is red on the original commit.
+The agent can edit only the frozen patch paths; the same checks and an independent review then gate
+the candidate-bound ship request.
+
+The command creates a branch and isolated worktree, but does not commit, push, open a pull request,
+or modify the source checkout.
+
+Runs checkpoint every completed phase in SQLite. After an interrupted controller process, resume the
+same worktree with:
+
+```bash
+cohorte --json --data-dir /path/to/data resume RUN_ID --live
+```
+
+`pause RUN_ID` and `cancel RUN_ID` are cooperative: an active provider turn finishes, then Cohorte
+records the completed phase boundary and stops before starting another phase.
+
+Delivery remains separately authorized:
+
+```bash
+cohorte --json --data-dir /path/to/data approve REQUEST_ID
+cohorte --json --data-dir /path/to/data ship RUN_ID --live
+cohorte --json --data-dir /path/to/data delivery-status RUN_ID --live --watch
+```
+
+`ship` rechecks the candidate hash and remote base, creates a commit with a run marker, pushes without
+force, then confirms the GitHub PR or GitLab MR through the provider CLI. Every effect is journaled
+before execution and reconciled on retry. It never merges or deploys.
+
+When `integrations.release_notes.enabled` is `true` in the project profile, `ship` appends a
+release-notes section to the PR/MR description. Its optional `heading` defaults to `Release notes`;
+its optional `template` defaults to `{title}\n\n{problem}`. Templates may use only `{title}`,
+`{problem}`, and `{acceptance}` (a bulleted list). Notes are omitted when the integration is
+disabled, and do not modify the reviewed candidate.
+
+Inspect and apply a bounded V2 metadata migration with an explicit rollback point:
+
+```bash
+cohorte --json --data-dir /path/to/data migrate \
+  --from-v2 /path/to/v2-copy --plan migration-plan.json
+cohorte --json --data-dir /path/to/data migrate --apply migration-plan.json
+cohorte --json --data-dir /path/to/data migrate --rollback /path/from/apply/backup.bak
+```
+
+The plan contains exact hashes, mappings, exclusions, losses and ambiguities. Apply fails if a
+source changed, imports no credentials or active run, and stores specs as historical artifacts that
+require V3 validation before build.
+
+Run the persistent local service used by protocol clients:
+
+```bash
+cohorte --json --data-dir /path/to/data service start
+cohorte --json --data-dir /path/to/data service status
+cohorte --json --data-dir /path/to/data service stop
+```
+
+On POSIX this uses a private Unix socket and verifies the connecting process belongs to the same
+user. On Windows it uses a local named pipe with a DACL restricted to the current user SID. No
+network port is opened. The lifecycle passes on GitHub-hosted Windows 3.12 and 3.13; release support
+still requires real-host and slow-client qualification.
+
+By default, Cohorte stores configuration and state outside target repositories using platform
+standard directories. Pass `--config-dir` and `--data-dir` for isolated automation. Cohorte never
+stores provider tokens.
+
+See [the implementation status](docs/IMPLEMENTATION.md), [qualification matrix](docs/qualification/README.md)
+and [protocol reference](docs/PROTOCOL.md).

cohorte_engine-1.0.0a1/README.md

@@ -0,0 +1,174 @@
+# Cohorte V3
+
+For Python dev releases, see [the release runbook](docs/RELEASING.md).
+
+Cohorte is a local, evidence-driven workflow engine for official coding-agent clients. This
+repository is a Python 3.12 rewrite built at the repository root. It does not depend on the former
+TypeScript/Pi implementations.
+
+The current pre-release provides the deterministic core, bounded feature and Patch
+workflows, and overlap-aware Fleet execution:
+strict contracts, a pure workflow reducer, SQLite persistence, immutable artifacts, project
+discovery, DAG validation, isolated Git worktrees, controlled checks, independent read-only review,
+a review/fix loop, a JSON-RPC stdio bridge, and a CLI. Codex authentication and live execution are
+capability-gated. A Claude Agent SDK adapter is available through the optional `claude` dependency
+and `agent_defaults.provider: claude`; a bounded single-surface Claude workflow has passed live
+build, checks and review on Darwin arm64.
+Passive `auth status claude` checks the native CLI without exposing credentials. An explicit
+`auth verify claude --live` probe is available after confirming the account to use.
+The connected native account passed the Claude SDK smoke, structured read, workspace edit,
+outside-write denial, a guarded read-only write denial, and CLI cancellation/pause/resume probes.
+G0 remains partial: the full login interaction and safe native session recovery inside a workflow
+are not yet qualified.
+Both adapters now persist common turn, tool and usage events for workflow runs. The event payloads
+contain provider, phase, access and bounded metadata, without prompts, responses, commands or file
+paths. SDK token accounting can differ, and Claude's reported cost is an estimate rather than a
+provider billing statement.
+
+```bash
+uv sync --all-extras
+uv run cohorte doctor
+uv run cohorte --json init /path/to/project
+uv run cohorte --json status
+uv run pytest
+```
+
+For external context, set `integrations.retrieval.provider` to `serena` or `graphify` in the
+project profile. Serena needs the installed `serena` MCP executable. Graphify-Labs needs the
+`graphify` optional extra and a prebuilt `<repo>/graphify-out/graph.json`; for a code-only graph,
+run `graphify extract <repo> --code-only --no-cluster --out <repo>` explicitly before retrieval.
+Both providers fail visibly when unavailable; file fallback requires
+`integrations.retrieval.fallback_to_files: true`. Figma design snapshots use a file or node URL in
+`integrations.design.source` and a locally supplied `FIGMA_ACCESS_TOKEN` with
+`file_content:read` scope. The token is never part of the profile. To verify a real Figma snapshot
+without printing its contents, run `python tests/live/verify_figma_snapshot.py --source <file-or-node-url>`
+in a shell where the token is already set, or enter it at the hidden prompt.
+
+Prepare a feature with independent product, architecture and QA sessions, then approve the exact
+completed spec before freezing it:
+
+```bash
+cohorte --json --data-dir /path/to/data brainstorm PROJECT_ID \
+  --feature-id safe-export --idea "Add a safe run export" \
+  --answer "Keep data local and require atomic output" \
+  --repo /path/to/project --output brief.json --live
+cohorte --json --data-dir /path/to/data spec-freeze-request draft.json \
+  --profile project.json --repo /path/to/project
+cohorte --json --data-dir /path/to/data approve REQUEST_ID
+cohorte --json --data-dir /path/to/data spec-freeze draft.json \
+  --profile project.json --repo /path/to/project \
+  --decision-id DECISION_ID --output frozen.json
+```
+
+The brainstorm keeps each native session reference, contribution and disagreement. Freeze rejects
+incomplete drafts and approvals for a different spec hash, profile, reference set or generated plan.
+
+Run the disposable Codex vertical with the included frozen example:
+
+```bash
+cohorte --json loop examples/g1/spec.json \
+  --profile examples/g1/profile.json \
+  --repo /path/to/disposable/repository \
+  --worktrees /tmp/cohorte-worktrees \
+  --run-id demo-1 \
+  --live
+```
+
+Run several frozen feature specs as an overlap-aware fleet:
+
+```bash
+cohorte --json fleet specs/feature-a.json specs/feature-b.json \
+  --profile project.json \
+  --repo /path/to/disposable/repository \
+  --worktrees /tmp/cohorte-fleet-worktrees \
+  --fleet-id release-train-1 \
+  --live
+```
+
+Fleet computes the cross-feature dependency graph, parallelizes disjoint features, serializes
+overlapping write sets, integrates each candidate in order and reruns its declared checks after the
+base changes.
+
+Capture a ticket, freeze a bounded patch, and run it with a pre-existing regression:
+
+```bash
+cohorte --json --data-dir /path/to/data intake PROJECT_ID --file ticket.txt
+cohorte --json --data-dir /path/to/data patch-spec \
+  --source-artifact-id SOURCE_ID --source-revision 1 \
+  --profile project.json --patch-id fix-total --title "Fix total" \
+  --reproduction "Run the regression test" --observed "It returns 6" \
+  --expected "It returns 5" --surface python --write-path calc.py \
+  --check regression --in-scope "Correct total" --rollback "Revert calc.py" \
+  --output patch.json
+cohorte --json --data-dir /path/to/data patch patch.json \
+  --profile project.json --repo /path/to/repository \
+  --worktrees /tmp/cohorte-patch-worktrees --run-id patch-1 --live
+```
+
+Patch refuses to build unless every declared automatic regression is red on the original commit.
+The agent can edit only the frozen patch paths; the same checks and an independent review then gate
+the candidate-bound ship request.
+
+The command creates a branch and isolated worktree, but does not commit, push, open a pull request,
+or modify the source checkout.
+
+Runs checkpoint every completed phase in SQLite. After an interrupted controller process, resume the
+same worktree with:
+
+```bash
+cohorte --json --data-dir /path/to/data resume RUN_ID --live
+```
+
+`pause RUN_ID` and `cancel RUN_ID` are cooperative: an active provider turn finishes, then Cohorte
+records the completed phase boundary and stops before starting another phase.
+
+Delivery remains separately authorized:
+
+```bash
+cohorte --json --data-dir /path/to/data approve REQUEST_ID
+cohorte --json --data-dir /path/to/data ship RUN_ID --live
+cohorte --json --data-dir /path/to/data delivery-status RUN_ID --live --watch
+```
+
+`ship` rechecks the candidate hash and remote base, creates a commit with a run marker, pushes without
+force, then confirms the GitHub PR or GitLab MR through the provider CLI. Every effect is journaled
+before execution and reconciled on retry. It never merges or deploys.
+
+When `integrations.release_notes.enabled` is `true` in the project profile, `ship` appends a
+release-notes section to the PR/MR description. Its optional `heading` defaults to `Release notes`;
+its optional `template` defaults to `{title}\n\n{problem}`. Templates may use only `{title}`,
+`{problem}`, and `{acceptance}` (a bulleted list). Notes are omitted when the integration is
+disabled, and do not modify the reviewed candidate.
+
+Inspect and apply a bounded V2 metadata migration with an explicit rollback point:
+
+```bash
+cohorte --json --data-dir /path/to/data migrate \
+  --from-v2 /path/to/v2-copy --plan migration-plan.json
+cohorte --json --data-dir /path/to/data migrate --apply migration-plan.json
+cohorte --json --data-dir /path/to/data migrate --rollback /path/from/apply/backup.bak
+```
+
+The plan contains exact hashes, mappings, exclusions, losses and ambiguities. Apply fails if a
+source changed, imports no credentials or active run, and stores specs as historical artifacts that
+require V3 validation before build.
+
+Run the persistent local service used by protocol clients:
+
+```bash
+cohorte --json --data-dir /path/to/data service start
+cohorte --json --data-dir /path/to/data service status
+cohorte --json --data-dir /path/to/data service stop
+```
+
+On POSIX this uses a private Unix socket and verifies the connecting process belongs to the same
+user. On Windows it uses a local named pipe with a DACL restricted to the current user SID. No
+network port is opened. The lifecycle passes on GitHub-hosted Windows 3.12 and 3.13; release support
+still requires real-host and slow-client qualification.
+
+By default, Cohorte stores configuration and state outside target repositories using platform
+standard directories. Pass `--config-dir` and `--data-dir` for isolated automation. Cohorte never
+stores provider tokens.
+
+See [the implementation status](docs/IMPLEMENTATION.md), [qualification matrix](docs/qualification/README.md)
+and [protocol reference](docs/PROTOCOL.md).