Codex Lead Engineer
152 lines
5.8 KiB
Markdown
152 lines
5.8 KiB
Markdown
# 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.
|