feat: operationalise project bus for Sandbox
This commit is contained in:
Codex Lead Engineer
@@ -0,0 +1,151 @@
|
||||
# Sandbox Activation Runbook
|
||||
|
||||
This runbook operationalises the Project Bus for the Epimonos Sandbox project.
|
||||
It does not itself authorize an internet-facing endpoint or replacement of the
|
||||
existing formal project channels.
|
||||
|
||||
## Authority and transition rule
|
||||
|
||||
WP-PA-001 is the accepted software baseline. WP-PA-002 covers deployment and
|
||||
activation. SG, PTO and the existing project threads remain authoritative
|
||||
until the independent reviewer returns `APPROVE` on the operationalisation
|
||||
commit and the Sandbox PM closes the WP-PA-002 gate with `ACCEPT`.
|
||||
|
||||
Before that gate, Project Bus records are shadow records. Differences are
|
||||
resolved in favour of the formal threads and recorded as corrections rather
|
||||
than silently rewriting history.
|
||||
|
||||
## Deployment preparation
|
||||
|
||||
1. Use a dedicated single-node host or controlled test VM.
|
||||
2. Keep the endpoint private unless PM-to-PO consultation has approved
|
||||
internet exposure.
|
||||
3. Copy `deploy/project-bus.env.example` to a root/service-owner-readable file
|
||||
outside the repository.
|
||||
4. Generate independent random bearer credentials of at least 32 bytes for
|
||||
SYSTEM, PO, PM, PA, Codex and Claude. Never reuse Git or account tokens.
|
||||
5. Replace the example values and set permissions to owner-read/write only.
|
||||
6. Configure TLS/authenticated ingress before any non-local exposure.
|
||||
7. Pin the reviewed Git commit or immutable image digest.
|
||||
|
||||
Start:
|
||||
|
||||
```bash
|
||||
docker compose --env-file /secure/path/project-bus.env \
|
||||
-f deploy/compose.yaml up -d --build
|
||||
docker compose -f deploy/compose.yaml ps
|
||||
```
|
||||
|
||||
The container must report healthy and run as the non-root image user.
|
||||
|
||||
## Project bootstrap
|
||||
|
||||
The bootstrap command reads the SYSTEM credential only from an environment
|
||||
variable. The manifest contains identities and roles, never credentials.
|
||||
|
||||
```bash
|
||||
export PROJECT_BUS_BOOTSTRAP_TOKEN='read-from-secret-store'
|
||||
project-bus-ops bootstrap \
|
||||
--endpoint http://127.0.0.1:8080/mcp \
|
||||
--manifest deploy/sandbox-project.json
|
||||
unset PROJECT_BUS_BOOTSTRAP_TOKEN
|
||||
```
|
||||
|
||||
Run the same command a second time. It must replay successfully and create no
|
||||
duplicate project, actor or event records.
|
||||
|
||||
After bootstrap, remove the SYSTEM credential from the steady-state service
|
||||
configuration and restart. Retain it offline only if the operating policy
|
||||
requires future project creation; otherwise rotate/revoke it.
|
||||
|
||||
## Actor connection and smoke test
|
||||
|
||||
For each actor credential:
|
||||
|
||||
1. call `initialize` without authentication;
|
||||
2. call `get_project` for `epimonos-sandbox`;
|
||||
3. verify returned roster and formal role expectations;
|
||||
4. call `sync_since` with that client's durable cursor;
|
||||
5. call `list_pending_actions`;
|
||||
6. persist the new cursor only after processing all returned events.
|
||||
|
||||
Store each actor token in that client's secret facility. Do not place tokens in
|
||||
`.mcp.json`, project instructions, prompts, shell history or Git.
|
||||
|
||||
Claude Code endpoint registration:
|
||||
|
||||
```bash
|
||||
claude mcp add --scope project --transport http \
|
||||
epimonos-project-bus https://approved-project-bus.example/mcp
|
||||
```
|
||||
|
||||
The endpoint configuration may be project-scoped; the credential must remain
|
||||
in a user/workload secret store.
|
||||
|
||||
## Initial shadow records
|
||||
|
||||
Once the actors authenticate, the PM registers WP-PA-002 through
|
||||
`issue_work_package`, Codex claims it, and the PA links the implementation
|
||||
commit and evidence. These records mirror the formal thread record during the
|
||||
bootstrap phase. Claude submits the independent review through both the
|
||||
existing formal channel and the bus.
|
||||
|
||||
The PM then closes the WP-PA-002 gate. Only an `ACCEPT` outcome after an
|
||||
independent `APPROVE` permits the separately recorded operational decision
|
||||
that the bus becomes the primary project interface.
|
||||
|
||||
## Backup and restore
|
||||
|
||||
Create a consistent online backup:
|
||||
|
||||
```bash
|
||||
project-bus-ops backup \
|
||||
--source /data/project-bus.db \
|
||||
--destination /secure/backup/project-bus-$(date +%Y%m%dT%H%M%S).db
|
||||
```
|
||||
|
||||
The command uses SQLite's online backup API and runs `PRAGMA integrity_check`.
|
||||
Copy the backup off-host under the applicable retention policy.
|
||||
|
||||
Quarterly and before primary-interface activation:
|
||||
|
||||
1. restore a backup into an isolated instance;
|
||||
2. start the exact reviewed application version against the restored database;
|
||||
3. authenticate with a temporary test credential;
|
||||
4. compare the restored maximum event cursor with the backup receipt;
|
||||
5. run `get_project`, `sync_since` and `list_pending_actions`;
|
||||
6. destroy the isolated restore instance and revoke the test credential.
|
||||
|
||||
## Rotation and revocation
|
||||
|
||||
Static-token changes require a restart in v0.1. Generate a replacement,
|
||||
update the external secret configuration, restart, verify the new credential,
|
||||
then remove the old credential and restart again. Treat exposure as an
|
||||
incident; rotate first and investigate from the immutable event trail and edge
|
||||
logs.
|
||||
|
||||
## Cursor recovery
|
||||
|
||||
Each consumer owns a durable cursor per project. When processing fails, retain
|
||||
the last successfully processed cursor and replay from it. Reads are safe to
|
||||
repeat; mutations require stable idempotency keys. Never advance a cursor
|
||||
before all returned events have been durably processed.
|
||||
|
||||
## Rollback
|
||||
|
||||
Before the activation gate, stop the bus and return solely to SG/PTO/project
|
||||
threads; no authority has transferred. After activation, announce the incident
|
||||
in the fallback formal channels, stop writes, preserve the database and logs,
|
||||
restore the latest verified backup if required, and record reconciliation
|
||||
events when service resumes. Never delete or edit prior events.
|
||||
|
||||
## Gate evidence checklist
|
||||
|
||||
- exact reviewed commit/image digest;
|
||||
- healthy non-root container;
|
||||
- two successful bootstrap runs with unchanged event cursor on replay;
|
||||
- successful authenticated checks for every formal actor;
|
||||
- backup receipt, restore result and matching event cursor;
|
||||
- secret scan with no credential material in Git;
|
||||
- independent Claude review report;
|
||||
- PM `ACCEPT` gate event and explicit primary-interface operational decision.
|
||||
Reference in New Issue
Block a user