DevRunbook-Public/FINAL_HANDOFF.md

# DevRunbook final handoff

## Delivered product

DevRunbook 0.1.0-rc.1 is a self-hosted, no-arbitrary-execution control plane
that turns governed playbooks, repository profiles, intent, constraints and an
autonomy level into deterministic prompts and Run Pack archives. The release
contains all 28 P0 packages, a searchable library, guided composer, immutable
run history, package authoring, read-only Gitea intelligence, local identity,
operations/audit views and production Docker/Unraid tooling.

## Release identity

- Version: `0.1.0-rc.1`
- Evidence commit: post-audit qualification on 2026-07-30 (see `release-evidence.json`)
- Database schema: nine forward migrations, `0000` through `0008`
- Runtime: Node.js 24, PostgreSQL 17.9, `linux/amd64`
- Validation deployment: private validation host (address intentionally redacted)
- Web image ID: `sha256:9679fab3cc033705f27a8f12eb92430f73f8b9f770cc309c8466f5a00e2e494f`
- Worker image ID: `sha256:982409b776484de5c14e1bbd206bf12f9379570b7f21562629d86ff42e38b63a`

## Verified capabilities

- 28/28 built-in packages import idempotently and the separate 72-entry roadmap
  catalog validates.
- Library search, facets, sorting, URL state, favorites, collections and
  lifecycle/quality presentation are implemented.
- Manual and Gitea-derived repository profiles retain immutable revisions,
  protected paths, inert commands and historical run snapshots.
- Observe through Repair autonomy, live deterministic preview, provenance,
  compatibility checks and blocking prompt lint are implemented.
- All 28 supplied minimal examples render byte-identically through the
  production TypeScript composer.
- Plain prompt, Markdown, AGENTS recommendation and deterministic Run Pack ZIP
  exports are persisted, authorized and re-importable without extraction.
- Local first-run ownership, password authentication, hashed/revocable sessions,
  invitations, password reset and workspace authorization are enforced.
- Gitea is read-only and optional; retained local snapshots/profiles remain
  usable during outage or after integration removal.

## Validation evidence

| Gate | Result | Evidence |
| --- | --- | --- |
| Clean installation | Pass | Isolated Compose project built from the documented path; setup `201`, repeat setup `409`, exact 28 built-ins, healthy after restart. |
| Migrations | Pass | Empty PostgreSQL 17.9 database applied all nine migrations; 36/36 integration tests passed and readiness remained `ready` after restart. |
| Built-in catalog | Pass | `scripts/validate_pack.py`: 28 P0, 6 normative examples, 72 roadmap entries, 9 schemas and valid API/spec contracts. |
| Core browser flows | Pass | Live library/composer/export/Gitea/Prompt Lab history plus M8 collection, operations and invitation flows; desktop and 390×844 checks; final fresh tab had no console warnings/errors. |
| Backup/restore | Pass | Strict-checksum backup `pre-m8-b2fb5a5`; isolated restore matched users, runs, artifacts, audits, migration count and all artifact SHA-256 values. |
| Security checks | Pass | 11/11 application security tests; dependency audit has no high/critical; Trivy web/worker 0 high/critical; Gitleaks 153 commits/0 leaks; licenses classified. |
| Performance targets | Pass | 10,000 versions, 30 iterations: search P95 241.913 ms (<500); detail P95 24.469 ms (<400). |
| Accessibility | Pass | Axe scanned Start, composer, Projects, My tasks, account and Management plus English/Dutch simple/expert matrices in desktop and narrow projects: 24/24 tests passed with no serious/critical findings. |
| Operations hardening | Pass | Unraid inspection proved read-only roots, all capabilities dropped, PID 256, 1 GiB memory and 64 MiB tmpfs for web/worker; status distinguishes observed evidence from unknown state. |
| Restart and restore | Pass | Restart retained 1 owner and 28 built-ins; isolated PostgreSQL restore matched 1 owner, 28 playbooks and 9 migrations before cleanup. |

The machine-readable requirement/gate matrix is `release-evidence.json`.
Supporting reports are under `evidence/` and milestone-by-milestone commands are
recorded in `CURRENT_STATE.md`.

## Deployment

From a release checkout, copy `.env.example` to a mode-`0600` environment file
and set independent random `POSTGRES_PASSWORD`, `SESSION_SECRET`,
`INTEGRATION_ENCRYPTION_KEY`, `BOOTSTRAP_TOKEN`, `PUBLIC_BASE_URL` and
`DEVRUNBOOK_PORT` values. Then run:

```sh
docker compose -p devrunbook-prod --env-file .env build
docker compose -p devrunbook-prod --env-file .env up -d
docker compose -p devrunbook-prod --env-file .env ps
curl --fail http://127.0.0.1:3000/health/live
curl --fail http://127.0.0.1:3000/health/ready
```

Complete `/setup` with the bootstrap token. Keep registration closed unless an
operator deliberately changes policy. Gitea configuration is optional.

For Unraid, set `UNRAID_APPDATA_ROOT`, create the restricted PostgreSQL,
artifact, content and backup paths described in `docs/operator-guide.md`, and
use:

```sh
export COMPOSE_FILE=docker-compose.yml:unraid/docker-compose.unraid.yml
docker compose -p devrunbook-prod --env-file .env build
docker compose -p devrunbook-prod --env-file .env up -d
```

## Upgrade

Create and copy a verified backup first. Run the read-only preflight:

```sh
docker compose -p devrunbook-prod --env-file .env run --rm migrate \
  ./packages/db/node_modules/.bin/tsx scripts/release/migration-preflight.mts
```

If the outcome is `ready`, stop web/worker, build the candidate, run the
one-shot migrate service and start web/worker. Down migrations are not provided;
rollback means restoring the pre-upgrade backup into an empty database and
starting the compatible retained image.

## Backup and restore

```sh
sh scripts/release/backup.sh \
  --project devrunbook-prod \
  --env-file "$(pwd)/.env" \
  --output /absolute/new/backup/directory \
  --application-version 0.1.0-rc.1 \
  --application-commit "$(git rev-parse HEAD)"
sha256sum --check --strict /absolute/new/backup/directory/SHA256SUMS
```

Preserve every integration encryption key version separately in an operator
secret store. Restore only into a new `devrunbook-*-restore-*` project:

```sh
sh scripts/release/restore-empty-target.sh \
  --project devrunbook-release-restore-001 \
  --backup /absolute/backup/directory \
  --env-file /absolute/restricted/restore.env
```

Verify readiness, authorization, counts and artifact/run digests before removing
the exact temporary restore resources.

## Known limitations

- Release qualification covers `linux/amd64`; no other architecture is claimed.
- Gitea is the only forge adapter and remains strictly read-only.
- There is no arbitrary repository command execution, Codex CLI bridge,
  semantic/vector search or automatic evaluation runner in this MVP.
- Product telemetry is disabled. Operators use health endpoints, structured
  logs, the operations console and audit events; no Prometheus endpoint ships.
- Docker/external logging owns operational-log rotation. Audit-event pruning is
  manual to preserve append-only governance until a reviewed archival policy is
  adopted.
- Development-only dependency findings, if any, remain outside the production
  runtime; the final production audit is enforced at high severity.

## Operator actions

- Replace validation-only secrets and hostnames; never copy the validation env.
- Store encryption keys and database credentials outside ordinary backups.
- Configure reverse proxy TLS, Docker log rotation and off-host backup copies.
- Monitor Docker storage capacity and retain write headroom for PostgreSQL;
  pruning unused build cache is safer than allowing the database volume to fill.
- Run artifact retention on the desired operator schedule.
- Review release evidence and limitations before creating a release tag; no tag
  was created automatically.