Metadata-Version: 2.4
Name: bpsai-pair
Version: 2.43.0
Summary: AI-augmented pair programming framework with 306 CLI commands for planning, orchestration, Trello/GitHub integration, and autonomous workflows
Author-email: BPS AI Software <support@paircoder.ai>
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://paircoder.ai
Project-URL: Documentation, https://paircoder.ai/#/docs
Project-URL: Repository, https://github.com/BPSAI/paircoder
Keywords: ai,pair-programming,cli,claude,gpt,codex,gemini,mcp,trello,github,autonomous,workflow,planning,tasks
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer<1.0,>=0.12
Requires-Dist: rich<16.0,>=13.7
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: ruamel.yaml<1.0,>=0.18
Requires-Dist: tiktoken<1.0,>=0.5.0
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: cryptography<51.0,>=50.0.0
Requires-Dist: keyring<26.0,>=25.0
Requires-Dist: fastapi<1.0,>=0.109.0
Requires-Dist: jinja2<4.0,>=3.1.0
Requires-Dist: uvicorn<1.0,>=0.27.0
Requires-Dist: sse-starlette<4.0,>=1.6.0
Requires-Dist: toggl<1.0,>=0.1.0
Requires-Dist: anthropic<1.0,>=0.76.0
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: packaging<27.0,>=21.0
Requires-Dist: click<9.0,>=8.0
Requires-Dist: platformdirs<5.0,>=4.0
Requires-Dist: tenacity<10.0,>=8.0
Requires-Dist: tomli<3.0,>=2.0; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest<10.0,>=8.0; extra == "test"
Requires-Dist: pytest-cov<8.0,>=4.0; extra == "test"
Requires-Dist: pytest-asyncio<2.0,>=0.21; extra == "test"
Requires-Dist: pytest-timeout<3.0,>=2.3; extra == "test"
Requires-Dist: pytest-xdist<4.0,>=3.5; extra == "test"
Requires-Dist: respx<1.0,>=0.21; extra == "test"
Requires-Dist: py-trello<1.0,>=0.19.0; extra == "test"
Requires-Dist: tomli<3.0,>=2.0; python_version < "3.11" and extra == "test"
Requires-Dist: setuptools<81.0,>=77.0.0; extra == "test"
Requires-Dist: wheel<1.0,>=0.47.0; extra == "test"
Requires-Dist: build==1.4.0; extra == "test"
Provides-Extra: trello
Requires-Dist: py-trello<1.0,>=0.19.0; extra == "trello"
Provides-Extra: github
Requires-Dist: PyGithub<3.0,>=2.1; extra == "github"
Provides-Extra: timer
Requires-Dist: toggl<1.0,>=0.1.0; extra == "timer"
Provides-Extra: mcp
Requires-Dist: mcp<2.0,>=1.0.0; extra == "mcp"
Provides-Extra: docs
Requires-Dist: sphinx<10.0,>=7.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4.0,>=2.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints<4.0,>=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton<1.0,>=0.5; extra == "docs"
Requires-Dist: myst-parser<6.0,>=2.0; extra == "docs"
Requires-Dist: sphinx-click<7.0,>=5.0; extra == "docs"
Provides-Extra: sandbox
Requires-Dist: docker<8.0,>=7.0.0; extra == "sandbox"
Requires-Dist: dockerpty<1.0,>=0.4.1; extra == "sandbox"
Provides-Extra: wizard
Requires-Dist: anthropic<1.0,>=0.76.0; extra == "wizard"
Provides-Extra: all
Requires-Dist: py-trello<1.0,>=0.19.0; extra == "all"
Requires-Dist: mcp<2.0,>=1.0.0; extra == "all"
Requires-Dist: docker<8.0,>=7.0.0; extra == "all"
Requires-Dist: dockerpty<1.0,>=0.4.1; extra == "all"
Provides-Extra: integrations
Requires-Dist: py-trello<1.0,>=0.19.0; extra == "integrations"
Dynamic: license-file

# PairCoder v2.43.0

> AI-augmented pair programming framework with 306 CLI commands

[![PyPI version](https://img.shields.io/pypi/v/bpsai-pair)](https://pypi.org/project/bpsai-pair/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Proprietary-red.svg)](LICENSE)

## Overview

**bpsai-pair** (PairCoder) is a comprehensive AI pair programming framework that provides structured workflows, enforcement gates, and integrations to ensure AI agents follow proper development practices.

- **Planning & Task Management** — Sprint planning, task lifecycle, Trello sync, and budget tracking
- **Skill-Based Workflows** — 9 built-in skills for TDD, code review, releases, architecture, and more
- **Integration Hub** — Trello, GitHub, MCP servers, and Toggl time tracking
- **Architecture Enforcement** — File size limits, function boundaries, import caps, and auto-split suggestions
- **Telemetry & Feedback** — Session telemetry, self-calibrating estimation, anomaly detection
- **Workspace Orchestration** — Multi-project workspaces, cross-repo contract detection, impact analysis
- **Intelligence Pipeline** — Usage snapshots, value extraction scoring, tamper detection
- **Interactive Setup Wizard** — Web-based project configuration with AI-guided setup
- **Licensing & Security** — Tiered feature gating, secret scanning, containment mode
- **Quality Control** — Browser-based QC with spec format, execution runtime, and gate enforcement
- **Containment Mode** — Tiered file access control via PreToolUse hooks
- **Autonomous Sprint Execution** — `bpsai-pair engage` runs full sprints: branch, tasks, PR, review, observations
- **Machine Interface** — `--json` envelope on all commands for programmatic consumption
- **Health Check** — `bpsai-pair doctor` validates setup with 9 checks and auto-repair
- **Slash Commands** — `/make-it-so` (intent to PR), `/draft-backlog` (engage-compatible backlogs)

## Installation

```bash
# Core installation
pip install bpsai-pair

# With integrations
pip install bpsai-pair[trello]      # Trello board sync
pip install bpsai-pair[github]      # GitHub PR management
pip install bpsai-pair[mcp]         # MCP server support
pip install bpsai-pair[all]         # All extras
```

## Quick Start

```bash
# Initialize a new project
bpsai-pair init

# Or use the interactive wizard
bpsai-pair wizard

# Check project status
bpsai-pair status

# Create a sprint plan
bpsai-pair plan new my-feature --type feature

# Start a task (with Trello sync)
bpsai-pair ttask start TRELLO-123

# Run architecture checks
bpsai-pair arch check

# Pack context for AI assistants
bpsai-pair pack
```

## Key Command Groups

| Group | Commands | Description |
|-------|----------|-------------|
| `plan` | 8 | Sprint planning, task creation, Trello sync |
| `task` | 12 | Task lifecycle, status updates, archival |
| `trello` / `ttask` | 27 | Trello board management, card workflows |
| `github` | 8 | PR creation, merge, auto-archive |
| `skill` | 8 | Workflow skills, export to Cursor/Windsurf |
| `license` | 10 | License management, feature gating |
| `telemetry` | 3 | Session telemetry, privacy config, export |
| `feedback` | 4 | Calibration, accuracy, task-type estimates |
| `workspace` | 5 | Multi-project orchestration, impact analysis |
| `arch` | 2 | Architecture enforcement, split suggestions |
| `budget` | 3 | Token budget tracking, task cost estimates |
| `security` | 4 | Secret scanning, containment mode |
| `qc` | 6 | Quality check specs, execution, reporting |
| `query` | 3 | Cross-agent state and telemetry queries |
| `engage` | 1 | Autonomous sprint execution from backlog |
| `fleet` | 1 | Workspace version compliance checking |
| `release` | 2 | Pre-release validation, version file checking |
| `containment` | 2 | File access enforcement and status |

## License Tiers

| Feature | Solo | Pro | Enterprise |
|---------|:----:|:---:|:----------:|
| Planning & tasks | Y | Y | Y |
| Skills & enforcement | Y | Y | Y |
| Setup wizard | Y | Y | Y |
| Telemetry & feedback | Y | Y | Y |
| Trello integration | | Y | Y |
| GitHub integration | | Y | Y |
| MCP servers | | Y | Y |
| Token budget & cost tracking | | Y | Y |
| Workspace orchestration | | Y | Y |
| Remote access & SSO | | | Y |

Check your license: `bpsai-pair license status`

## What's New

> Full release history and detailed notes: [paircoder.ai](https://paircoder.ai).

**v2.43.0 — engage hardening + the measurement era**
- **A run branch can no longer be created from nothing.** Engage resolves its base up front and refuses before any git operation when that resolution fails, instead of falling through to an orphan branch whose first commit snapshots the entire tree.
- **A task is done only when its lifecycle commit verifies on origin**, and a task that depends on work not in this dispatch is refused before any branch is cut.
- **Model routing runs on measured complexity, not a hardcoded constant.** The complexity seam is a provenance-stamped calibration parameter — a value with no provenance is refused rather than silently governing dispatch — with a staleness guard so it cannot become a number written once and read forever.
- **A project with no calibration data is no longer refused on a duration it has never measured**, and refusal text now says when a number is a default rather than a measurement.
- **The protected-branch guard judges every path an event names**, closing a decoy-key bypass; agent-memory writes work again on a protected branch; and the bypass audit ledger has one location instead of two.
- **The permission floor stops printing a warning wall at every session start and close** — its dead `Write(...)` deny rules are removed on upgrade, with identical coverage.

**v2.42.0 — Trustworthy telemetry, a hang-proof completion path, and a release that dogfoods itself**
- **Telemetry honors the privacy level you configured, everywhere it's recorded.** Every record-construction site resolves privacy through a single resolver instead of scattered literals, so a "minimal" setting can no longer leak through a path that hardcoded "full".
- **Aggregate telemetry reports reflect the population they cover**, and `telemetry coverage` shows what was recorded versus what was configured — field population rates, source mix, and privacy divergence.
- **A stuck OS keyring can no longer hang task completion.** `task update --status done` / `ttask done` detect non-interactive contexts and bound any keyring access with a timeout, instead of blocking indefinitely on a keyring backend prompting for an unlock.
- **A fleet member declared at a nested path is found by its real declared location**, not a same-named stray directory sitting at the scan root — closing a `fleet check`/`fleet inventory` false "not installed" result.
- **Every release now proves itself against a real consumer repo before it can go out.** A new dogfood gate builds the release wheel, installs it hermetically into a scratch venv, and runs a battery of drifted-fixture scenarios against it.

**v2.41.3 — Upgrade commits tell the truth**
- **If upgrades kept leaving `.claude` changes uncommitted "for review" on a repo you never hand-edited, or fleet upgrades still rolled back even after v2.41.2, this closes it.** The `.claude` payload hold now applies per file and only to files an upgrade run did not write, `"Upgrade committed to git."` now reports the real git outcome (commit SHA, or an honest blocked/nothing-to-commit reason) with a non-zero exit when it could not commit, and unattended fleet upgrades commit cleanly on protected branches again.

**v2.41.2 — Fleet upgrade race, fully closed**
- **If your fleet upgrade still rolled back on v2.41.1, this completes the fix.** The background startup sync no longer races the explicit `upgrade` command — one process performs the upgrade and commits it, on every path (interactive, `--auto`, and the fleet transaction).

**v2.41.1 — Upgrade-commit fix for the v2.41.0 fleet rollback**
- **If a v2.41.0 upgrade left your repo dirty, or a fleet upgrade rolled back, this is the fix.** `upgrade --auto --commit` now derives what to commit from what the upgrade run wrote or deleted, instead of a fixed pattern list that a new artifact class could fall outside of.

**v2.41.0 — Fail-closed completions and security scans, git-layer branch protection, honest fleet attestation**
- **Task completions can no longer silently skip acceptance-criteria verification.** The completion path fails closed with a recorded reason on every route.
- **Behavior change: security scans fail closed instead of reporting clean without scanning.** A `scan-deps` run that resolves zero packages, or whose audit process crashes or returns unparseable output, is no longer treated as a passing result. If a CI scan starts failing after upgrading, it was never really scanning.
- **Protected-branch enforcement now happens in git itself**, on the commit operation, not only through tool-call matching.
- **Hooks can never write or stage upgrade scaffolding**, even as a side effect of a background check.
- **Engage runs survive killed or hung child processes** without stalling, and checkpoint in-progress work to a recovery branch on an interval.
- **Release attestations are honestly ordered** — website confirmation lands before a release is tagged, fleet confirmation moves to a post-publish step.
- **Fleet inventory labels members vs. local-only repos**, and a new `fleet verify-agent-config` command reports settings drift.
- **Model recommendations and `engage --dry-run` advisories can account for task complexity**, not only task type, falling back honestly to the doctrine table when the data does not support a confident, differentiated pick.

**v2.40.0 — Contained residue, converged upgrades, quieter reviews**
- **Run artifacts are scanned before they are committed.** Engage run residue passes the full secret battery; a hit is held in a gitignored quarantine path and a sanitized placeholder is committed in its place.
- **Upgrades converge.** A dry run after an upgrade no longer re-proposes changes that already applied, and a healthy upgrade reports as one consolidated summary.
- **Reviews carry signal.** Findings pass a skeptic stage before reaching the report, formatting gates skip repos that do not use them, and test files are measured against test limits.
- **`status` reads context-sync state.** A repo that tracks progress without plan records shows its real phase and next action.
- **The base-branch guard has a reachable opt-out.** A marker file disarms it, and disarming announces itself.

**v2.39.0 — Multi-provider foundations and run-exit contracts**
- **Experimental local-model dispatch.** Multi-provider foundations land alongside the existing hosted path.
- **Engage preflight runs all at once.** A single battery plus `engage doctor` reports every blocker in one pass instead of one per attempt.
- **Sibling checkouts restore on every run exit**, including circuit-breaker exits; a failed restore prints a loud contract-violation line.
- **Refusals print runnable remediation.** Engage emits executable recipes rather than prose descriptions of what to do.
- **Smaller config surface.** `config.yaml` reduces to a user-owned core; tool-owned sections refresh on upgrade with an audited, secret-masked diff.
- **`require_feature_branch` defaults to enforced.** An unset key means enforced after upgrade; an explicit `false` is kept permanently.

**v2.38.0 — Done means verified**
- **Acceptance criteria are enforced, not aspirational.** Engage completion now runs the same strict-AC gate as manual task completion; unverified criteria land a task as blocked with an audited bypass, never silently done.
- **Verifiers can't fail open.** Single-file provenance checks actually scan (or refuse loudly), and baseline generation merges instead of clobbering the repository-wide baseline.
- **The statusline tells the truth.** Real durations, costs from the single pricing source of truth, and estimates labeled as estimates.
- **Untrusted text stays contained.** PR bodies get full credential/PII scrubbing and blockquote containment; refusal classification uses the provider's own stop reason.

**v2.37.0 — Opus 5, reliability, and honest benchmarks**
- **Claude Opus 5, day-one support.** Registry, pricing, wizard picker, and a benchmark-panel row — while model routing deliberately stays on measured evidence, not release hype.
- **A tier that still discriminates.** `hard-plus` fixtures restore separation above the saturating hard tier, so frontier models keep producing routing signal.
- **Engage runs you can trust.** Resume actually skips completed tasks; a safe `cleanup-orphans` sweeper (dry-run first, preserved work excluded); a machine-level cap stops runaway concurrent runs from exhausting your machine.
- **Benchmarks tell the truth.** Refusals are classified only on real metered attempts, privacy settings are honored end-to-end and fail closed, and a `matrix-regrade` command rebuilds reports from retained artifacts at zero API cost.

**v2.36.0 — Benchmarks that discriminate, prices that reconcile**
- **Difficulty tiers separate the field.** Fixtures now carry `easy`/`medium`/`hard` tiers with 10 new hard fixtures; reports score per tier, so models that all ace small tasks still rank meaningfully on hard ones.
- **Conditions are first-class rows.** Pin thinking on/off and reasoning-effort per row (`model@effort`) and compare a model against itself, not just against others.
- **One pricing source of truth.** Five divergent internal price tables are unified; OpenRouter prices auto-resolve from the live catalog, reasoning tokens are counted, and recorded costs reconcile against what providers actually bill.
- **Sturdier autonomous runs.** Engage lands driver commits on the intended branch under worktree isolation, reports aborted runs honestly, guards each benchmark row against empty/null provider output, and the security-audit gate now reads the real branch diff.
- **Faster CI, governed releases.** Python CI shards 4-way (~4-minute cycles); releases pin a hash manifest of the shipped `.claude/` payload so fleet upgrades auto-commit only on an exact match.

**v2.35.2 — Benchmarks join reality, QC agent regains its browser**
- **Benchmark fixtures speak your task types.** The matrix fixture set is re-keyed to the vocabulary real projects actually use (`feature`, `bugfix`, `chore`, `refactor`, `review`), with legacy strings alias-normalized at ingestion — so `benchmark matrix-run --auto-seed` primes the same calibration cells your production tasks read, instead of cells nothing joins.
- **Fixtures can't over-demand.** A fail-closed fixture lint rejects any fixture whose grading requirements aren't explicitly stated in its own prompt, ending a class of false cross-model failures.
- **Divona sees Chrome again.** The QC agent's tool allowlist had excluded the browser tools entirely; it now inherits the full toolset and knows to load deferred browser tools before assuming they're absent.
- **GitHub Release notes publish again.** The release workflow's notes extraction wrote to the wrong stream in CI, shipping empty release bodies; notes now publish with every release.

**v2.35.1 — Telemetry restored, typed git-failure handling, memory seed packs**
- **Driver telemetry records again under parallel lanes.** v2.35.0's run-root worktree isolation sent driver-task telemetry into the ephemeral worktree, which is destroyed at run teardown — runs recorded zero driver rows. Telemetry now lands in the durable checkout, and calibration reads from the same place.
- **Git and GitHub failures are classified, not guessed.** A typed failure taxonomy (transient / ambiguous / permanent) drives retries — unrecognized failures are never auto-retried — and error text is scrubbed of tokens and credentials.
- **`engage` commit and branch seams fail closed.** A staging failure now fails the task instead of silently dropping its diff, branch reuse must be provably safe, cross-repo dispatch fetches a missing base branch on demand, and a halted run can no longer exit 0 and cut a PR.
- **Runtime memory seed packs.** `init`/`upgrade` seed Claude Code's harness memory with shipped doctrine (provenance-stamped, refresh-on-write, organic memories untouched).

**v2.35.0 — Parallel lanes, governed actions, fleet threat scanning**
- **`engage` lanes run in parallel.** Each run's bookkeeping lives in an isolated worktree cut from the declared base, so multiple lanes no longer contend on one shared checkout (`--no-worktree` opt-out available), and a fail-closed count guard refuses dispatch if any task heading fails to parse.
- **Enforcement moves to the action seam.** An intent layer routes requests, artifact-chain preconditions replace prose-as-command, ad-hoc bypasses are audited, and tasks marked `privileged` run only through an isolated executor.
- **Scan your fleet against advisories.** `bpsai-pair advisory scan` takes an affected-package list (with CVE ids) and reports impacted repos across requirements/pyproject/package.json/lockfiles, with a `--fail-on-impact` exit code.
- **Upgrades know your stack.** A file-ownership manifest separates tool-owned from project-owned files, Node projects get Node verification workflows, and `fleet audit-workflow-md` reports stack-mismatched files before anything is touched.
- **Scheduler and run exits tell the truth.** Ready tasks dispatch in dependency order without false cascade-aborts, blocked-task residue can no longer delete sibling task files, and circuit-breaker aborts exit non-zero.

**v2.34.0 — One completion pipeline, safer credentials, self-healing state**
- **Acceptance criteria verify the same way everywhere.** `task update`, `ttask done`, and MCP completion tools now run through one reconciled completion pipeline instead of two separate legacy checkers.
- **Trello gets tougher and safer.** Requests retry with backoff and jitter on rate limits/server errors (honoring `Retry-After`), a board-index cache avoids repeated full-board scans, and credentials move from a plaintext file into your OS keyring (with automatic migration and a headless-CI fallback).
- **`state.md` heals itself.** Status data lives inside a managed fence that only PairCoder rewrites; a missing or damaged fence is repaired automatically instead of silently degrading `bpsai-pair status`. Phase/Goal/Last Action/Next are now derived from structured data instead of parsed prose.
- **Fleet upgrades are transactional.** A clean-tree precondition, automatic verify-and-rollback, and a single scoped commit — with anything under `.claude/` left staged for your review.
- **`engage` has a formal run-exit contract.** Every run enforces a clean-tree boundary at each lifecycle hand-off, reports a distinct `blocked` status, scopes commits to their actual diff, and preserves (rather than discards) recovery data on failure, with any recovered secrets quarantined.
- **New `--role driver|navigator` option** on `task update`/`ttask done` so interactively-run navigator work isn't miscounted as driver telemetry, and `plan estimate` now reports whether each estimate came from config, calibration, or a default.

**v2.32.0 — Safer timeouts, honest audits, tighter project-management guards**
- **Drivers get more room, and safer interventions.** The default engage task timeout rises from 30 to 90 minutes, and a stuck driver is now nudged with a graceful `SIGTERM` — after two consecutive stuck check-ins — before any hard kill, so long-running work is no longer discarded prematurely. An explicit repo config value still wins.
- **The pre-PR security audit gate matches the merge bar.** P0/P1 findings block the PR; P2-only findings post as a non-blocking comment instead of false-blocking the release.
- **Bypass audits speak the real vocabulary.** `audit bypasses --type` now filters on the actual per-flag bypass values (`no_strict`, `local_only`, `force_local`, `allow_dirty`, and the rest); the old catch-all `user_override` type is kept only for historical entries.
- **Project-management sync got more honest.** A read-only reverse sync reports a distinct `FETCHED` action instead of a misleading `UPDATED`, an acceptance check for a work item that has vanished from the board now fails closed instead of auto-completing, and a custom workflow with an unknown terminal target now errors on load instead of passing silently.
- **Token estimates default to live calibration.** New projects no longer ship a live `token_estimates:` section — delete any stale one left by an older template to restore calibration-driven estimates.

**v2.31.0 — Smarter routing, honest telemetry, benchmark-calibrated estimates**
- **Model routing can now explore.** Opt-in `routing.exploration.epsilon` occasionally samples an equally-qualified model from the routing band so your calibration data learns which models actually perform best on your tasks — off by default, deterministic when off, and every assignment is logged for analysis.
- **Telemetry tells the truth.** Task records now capture whether acceptance criteria actually passed (`ac_verified`), real per-session token baselines, what changed (lines/files), and which model really ran — the data your `calibration report` learns from is now correctness-based, not survival-based.
- **Benchmarks that know their place.** `benchmark matrix-run` runs natively (faster, no co-install), prices local models at $0, validates provider keys up front, and its seeds act as decaying cold-start priors — real production data automatically outweighs synthetic seeds as it accumulates.
- **Architecture checks, calibrated.** Role-aware caps are now opt-in (`architecture.role_defaults: true`), count only code lines when configured, and grandfathered debt lives in reviewable baseline files instead of blocking unrelated work.
- **First-run polish.** New projects show a real date and their branch name from the first `status`, before the first commit.

**v2.30.1 — Review noise fix (patch)**
- The code-review wiring guard now honors the `.wiring-baseline.json` allowlist correctly — reviews flag only NEW unwired code instead of re-reporting pre-existing debt on every pull request.
- Internal reliability and test-stability fixes.

**v2.30.0 — Sprints that finish what they start**
- **Sprints can no longer end silently incomplete.** Every completed sprint ends with a PR (the run refuses to exit without one), merged branches are cleaned up automatically, and issues referenced by the work are closed with an evidence comment.
- **`bpsai-pair fleet audit --branches --issues`** — one command reports leftover branches and unclosed-but-fixed issues across every repo in your workspace.
- **`review sprint <id>` audits multi-repo sprints as a whole** — one review pass over every repo the sprint touched, catching integration issues per-repo reviews miss.
- **Review findings become data you can analyze.** Every review — including clean passes — records per-finding data (agent, file, line range, defect class) locally for your own quality analytics.
- **Fixes.** Engage PR creation no longer fails on very long descriptions; `fable` model alias recognized in model config.


- Cross-repo engage runs no longer false-fail a healthy task when a diff check errors, and a task's completion verdict and sibling-repo commit both land in the actual target repo instead of the run repo.
- `engage --dry-run` now shows each task's resolved target repo, and preflight warns (or, with `--strict-targets`, refuses) when a task's description implies a sibling-repo target that failed to resolve — catching the authoring mistake before dispatch.

**v2.29.0 — Full model routing for the latest Claude models**
- **Route every task to the model built for it.** Full model-routing support across the current Claude lineup (Fable 5, Sonnet 5, Opus, Haiku): `/pc-plan` and `/draft-backlog` assign a `model:` to every task, and one unified router applies the same explicit > calibration > complexity precedence everywhere a model decision is made — engage dispatch, advisory hooks, and `--dry-run` previews always agree.
- **More output from every token.** Plan-time routing keeps frontier models on the reasoning-heavy work and fast models on the high-volume driver work — increasing throughput while maximizing token efficiency across a whole fleet of agents.
- **Routing that improves itself.** Telemetry records `routed_model`, `routing_tier`, and `session_role` per task; `bpsai-pair calibration report` recomputes calibration and flags drift between what was routed and what actually ran — so routing gets sharper with every task you complete.
- **Engage reliability.** Completion no longer false-blocks on already-landed work; cross-repo runs push sibling-repo branches at kickoff and after every task gate for crash durability; pushes always target the intended branch.
- **Code review reliability.** `review pr`/`review branch` run their checks against an isolated copy of the reviewed code — no more false failures from a busy checkout.

**v2.28.2 — Latest-model support + engage durability (patch)**
- Claude Sonnet 5 and Fable 5 selectable in the wizard/config; current-gen context limits corrected to 1M for accurate budgets.
- Engage pushes its branch at kickoff and after every task — crash durability + mid-run visibility.
- Fixes: engage on Windows, `support create`/`list` scope, `upgrade` artifact hygiene, fail-closed `review pr`, engage auto-PR `--head`.

**v2.28.0 — Cross-repo engage, provider-agnostic PM, plan-time arch headroom (minor)**

- **Cross-repo engage.** A sprint can target sibling repos — engage commits, branches, opens PRs, and verifies in the right repo per task; backlogs declare a `Target repo:` (backlog-level or per-task), and QA/security/review fan out across every touched repo.
- **Provider-agnostic project management.** `pm.provider` defaults to `none` — tasks are local files completed with `bpsai-pair task update <id> --status done`; Trello is opt-in. New `bpsai-pair pm` command group; backlog cards with status rollup.
- **`bpsai-pair arch headroom`** — reports files approaching their architecture caps so you can plan an extraction before a change is forced to "trim to fit"; surfaced automatically when engage starts.
- **Engage completion-gate unification (`--engage-mode`)** plus a race-immune per-task start record, ending a class of flaky completion gates.

**v2.27.1 — Patch**

- Fixed a CLAUDE.md upgrade that could duplicate the `Slash Commands` / `CLI Reference` sections. Upgrade now keeps only your `## Project-Specific Notes` section and refreshes the rest from the canonical template.

**v2.27.0 — Multi-provider groundwork, engage hardening, new lints**

A minor release: groundwork for alternate model backends, engage-lifecycle hardening, and two author-time architecture lints.

- **engage lifecycle hardening.** A gate error printed to stdout could be misread as a transient API failure and retried with the wrong cause; the retry now reads both output channels and fails fast with the real reason. The dirty-tree gate is churn-aware (no longer trips on engage's own bookkeeping), the planning artifact is reconciled to a single id, lifecycle hooks resolve regardless of PATH, and a fast task-cycle "PR storm" is fixed.
- **`bpsai-pair arch check-encoding`** — flags text-mode file I/O missing an explicit `encoding=` (the Windows cp1252 crash class) at authorship time.
- **`bpsai-pair arch check-wiring`** — advisory lint catching code that's written and unit-tested but never wired into the live flow.
- **`upgrade` preserves your CLAUDE.md notes.** Upgrade refreshes CLAUDE.md to the canonical template while keeping your `## Project-Specific Notes` section.
- **Harness-adapter groundwork.** Experimental scaffolding (`config provider` presets for OpenRouter, Ollama, Azure, and more) toward alternate model backends; Claude Code remains the harness.

**v2.26.1 — Cross-platform & telemetry robustness (patch)**

- Fixed a Windows `UnicodeEncodeError` crash when engage diffs contained non-cp1252 characters (tempfiles now written as UTF-8).
- `telemetry aggregate` now reads the correct source instead of discarding records, and tolerates a missing telemetry file.

**v2.26.0 — Engage Workspace Pre-flight + Liveness**

- Cross-repo engage runs are gated by a pre-flight check: a covering `.paircoder-workspace.yaml` must list every target repo, or dispatch is refused with guidance.
- Long-running tasks emit a liveness heartbeat and honor a configurable per-task timeout. Adds `bpsai-pair workspace validate`.
- Review agents get an explicit turn budget (fixes empty/partial reviews) and large PR diffs are no longer truncated. Tasks can declare structured metadata (`target_repo`, `depends_on`) in a YAML block.

**v2.25.7 — Bootstrap correctness + auto-upgrade discipline**

- The remote-session bootstrap now fires only in Claude Code cloud sessions (`CLAUDE_CODE_REMOTE=true`); local and headless sessions are untouched (force with `PAIRCODER_BOOTSTRAP_FORCE=1`).
- Auto-upgrade no longer silently commits — it stages the re-templated `.paircoder/` files for review and notifies on stderr (restore the old behavior with `BPSAI_UPGRADE_COMMIT=1`).

**v2.25.6 — Hotfix: remote-session bootstrap tracks the release**

- The remote-session bootstrap pin and its dependency set are corrected so fresh remote/CI/engage sessions install the current CLI.

**v2.25.5 — Engage hardening (round 2) + spend visibility**

- Stricter backlog dependency parsing, transient-failure retries on lifecycle/planning dispatch, cross-repo dispatch via a `**Target repo:**` declaration, a `--preserve-failed-branch` recovery flag, and transactional backlog materialization.
- New `bpsai-pair budget programmatic` reports month-to-date API spend against your configured tier cap, with an optional monthly cap that can gate dispatch.

**v2.25.4 — Engage reliability + provider env-var presets**

- Documentation/content tasks are recognized as completed work; running engage against a plan file points you to `/draft-backlog`; `**Acceptance criteria:**` is accepted as a synonym for `**AC:**`.
- New `bpsai-pair config provider <name>` prints environment-variable presets for the major Anthropic-API-compatible providers (Anthropic, OpenRouter, Ollama, LM Studio, Azure), plus a providers guide.

**v2.25.3 — CLI hardening + test parallelization**

- Test suite parallelized for a ~10× speedup; license machine-binding enforced; a UTF-8-safe subprocess wrapper closes the Windows cp1252 crash class; new `bpsai-pair arch check-subprocess` lint.

**v2.25.2 — Engage stability + Windows UTF-8 fix**

- Windows engage made usable (UTF-8 sweep); quieter hook chain; workspace scope-leak fix; more precise task-file matching.

**v2.25.1 — Engage hook-failure hotfix**

- Hook failures propagate correctly instead of being swallowed; security findings are visible when engage blocks a PR.

**v2.25.0 — Engage driver intelligence + pipeline reliability**

- Skip already-completed tasks on retry; recognize driver self-commits; `bpsai-pair preflight` runs CI-matching tests before pushing.

**v2.24.0 — Sweep: diff-aware dead-code cleanup**

- `bpsai-pair sweep` finds dead imports, orphaned tests, and stale helpers after changes, with `--fix` for high-confidence removals.

**v2.23.x — Engage reliability, resume, and lifecycle hardening**

- `engage --resume` skips completed tasks on retry; human-gated tasks via `requires: human` in backlog frontmatter; branch lifecycle flags; more reliable automated task completion.

**v2.22.0 — Agent identity + Vaivora review agent**

- Named review agents (Nayru, Laverna, Bellona, Vaivora, Divona); a third review agent engages automatically for large diffs.

**v2.21.x — Review command, enforcement, and observability**

- `bpsai-pair review pr/branch/task`; targeted per-task tests; intent recognition and an approval gate for autonomous dispatch; protected-branch guard.

**v2.20.0 — Engage pipeline**

- `bpsai-pair engage` runs full sprints autonomously (branch, tasks, PR, review); `/make-it-so` (intent to shipped PR); `bpsai-pair doctor` health checks with `--fix`.

## Documentation

- [Website & Docs](https://paircoder.ai)
- [Quick Start Guide](https://paircoder.ai/docs/getting-started/)

## Requirements

- Python 3.10 or higher
- Git (for project management features)

## Support

- Email: support@paircoder.ai
