Publish DevRunbook source

FINAL_HANDOFF.md

@@ -0,0 +1,150 @@
+# 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.