Metadata-Version: 2.4
Name: project-board
Version: 2026.9.26.2220
Summary: The Project Board client: the pb command a machine runs to join a board, receive addressed work, and report on it, with the shared contract both sides speak.
Author: Elena Viter
License: MIT
Project-URL: Homepage, https://github.com/elenaviter/app-ecosystem
Project-URL: Repository, https://github.com/elenaviter/app-ecosystem
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp<4,>=3.9
Requires-Dist: app-foundation[data-bus]<2027,>=2026.09.26.2220
Requires-Dist: connection-hub[client]<2027,>=2026.09.26.2220
Requires-Dist: mcp==2.0.0
Requires-Dist: packaging<27,>=23
Requires-Dist: PyYAML<7,>=6
Requires-Dist: service-foundation<2027,>=2026.09.26.2220
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: pytest-asyncio<2,>=0.23; extra == "test"
Requires-Dist: pytest-xdist<4,>=3.8; extra == "test"

# project-board

The Project Board client: the `pb` command a machine runs to join a board.

## Install from reviewed source

```bash
APP_REPOSITORY=/path/to/app-ecosystem
APP_COMMIT=<approved-full-commit>
APP_EXPORT=$(mktemp -d)
test "$(git -C "$APP_REPOSITORY" rev-parse "$APP_COMMIT^{commit}")" = "$APP_COMMIT"
git -C "$APP_REPOSITORY" archive "$APP_COMMIT" | tar -x -C "$APP_EXPORT"

python3 \
  "$APP_EXPORT/products/project-board/packages/project-board/scripts/install_from_source.py" \
  --source-root "$APP_EXPORT"
"$HOME/.local/bin/pb" procedure install --target codex --target claude-code

# After pb setup creates the target configuration:
"$HOME/.local/bin/pb" source use-code \
  --repository "$APP_REPOSITORY" \
  --ref "$APP_COMMIT" \
  --expect "$APP_COMMIT"
```

The source installer creates and smokes one complete release environment and
installs an inert user launcher for `releases/current`. Its one `pip install`
invocation resolves the four first-party distributions (`project-board`,
`app-foundation`, `service-foundation`, and `connection-hub` with its `client`
extra) from the clean export together with their third-party dependencies. The
client needs no KDCube package and no Connection Hub command line (W322). The
checkout is not an import path. `pb source status` reports the active release
and environment, launcher version, target receipt, the App Ecosystem commit,
every selected package tree, and the source reported by the supervised relay.

## Package contents

- `project_board.client`: the `pb` command. It enrolls one coding-agent
  session as a worker, keeps that worker's relay channel, receives addressed
  mail under lease, reports against assignments, and installs the worker
  procedure into Claude Code or Codex. Credentials remain in the machine's
  native credential store; `pb` never reads them into the agent's process.
- `project_board.contract`: the references, worker identity, operation
  outcomes, plan shapes, and mail contracts that the client and the server
  both speak, defined once here.
- `project_board.procedures`: the operator, worker-host, setup, testing, and
  live-acceptance runbooks that travel with the client they operate.

The server side stays in its own repository and depends on this package for
the contract.

What the relay keeps on the host (the outbox, reconciliation receipts, mail,
leases and markers), how each store is partitioned, its retention bound and the
`relay store read` log line are in
[Storage and retention](../../docs/storage-and-retention.md#relay-local-state).

## Select host source

A published distribution remains a supported independent source. Install and
smoke its complete release environment, make it current, and verify the relay
restart with:

```bash
pb source use-release --expect-version 2026.09.26.2220
```

The source deployment selects one reviewed App Ecosystem commit:

```bash
pb source use-code \
  --repository /path/to/app-ecosystem \
  --ref <commit-or-ref> \
  --expect <full-40-character-commit>
```

The code release is exported from Git objects and verified blob by blob. It
contains `project-board`, `app-foundation`, `service-foundation`, and
`connection-hub` from the App Ecosystem commit. The commit and package trees
form one path-independent release ID. A release selected before W322 also
named `connection-hub-cli` and a KDCube commit; it stays readable, keeps its
id, and can still be rolled back to. One host-wide `releases/current` pointer is
shared by the `pb` launcher and every relay definition; each target keeps its
source-action receipt. An installed relay must report the candidate source
before the switch succeeds. A failed start restores the previous current
release and target receipt.

Running `python -m project_board.client.entrypoint` with checkout package paths
on `PYTHONPATH` is an explicit development process. It does not change the
host selector, and `pb status` reports that process as unpinned checkout code.

## Why it is packaged

A machine that runs agents installs one package family and selects one durable
source manifest. Commands and the relay therefore load the same reviewed
implementation, while the release ID, repository commits, and package-tree
identities give deployment and status checks precise facts to compare.
