Publish DevRunbook source

2026-09-03 04:09:17 +02:00
commit cfd2804e27
928 changed files with 161642 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 40 — Bootstrap repository contract
+
+## Purpose
+
+This document fixes the initial implementation shape so Codex does not spend Milestone 0 redesigning routine repository mechanics.
+
+## Required root structure
+
+```text
+apps/
+  web/
+  worker/
+packages/
+  application/
+  artifacts/
+  config/
+  content/
+  db/
+  domain/
+  integrations/
+  observability/
+  composer/
+  testing/
+  ui/
+content/playbooks/
+schemas/
+api/
+docs/
+tests/
+  integration/
+  e2e/
+  security/
+```
+
+Use `pnpm` workspaces. Turborepo is the default local task orchestrator with remote caching disabled unless explicitly configured later. The implementation may refine package names only before Milestone 1 and must update architecture references atomically.
+
+## Required root commands
+
+The root `package.json` must expose stable operator and CI commands:
+
+- `pnpm format`
+- `pnpm format:check`
+- `pnpm lint`
+- `pnpm typecheck`
+- `pnpm test`
+- `pnpm test:integration`
+- `pnpm test:e2e`
+- `pnpm test:security`
+- `pnpm build`
+- `pnpm dev`
+- `pnpm db:generate`
+- `pnpm db:migrate`
+- `pnpm db:status`
+- `pnpm content:validate`
+- `pnpm content:import`
+- `pnpm verify`
+
+`pnpm verify` is the local release-oriented aggregate and must include formatting check, lint, typecheck, unit tests, build-pack validation and production build. Integration, browser and security suites may remain separate where they require services, but CI and release gates must run them.
+
+## Required baseline files
+
+Milestone 0 creates and verifies:
+
+- `package.json` and lockfile;
+- `pnpm-workspace.yaml`;
+- `turbo.json` without required remote cache;
+- strict base TypeScript configuration;
+- `.editorconfig`, `.gitignore` and root `.env.example`;
+- typed configuration package;
+- Drizzle configuration and initial migrations;
+- Vitest and Playwright configuration;
+- Dockerfile with separate web and worker targets or roles;
+- Docker Compose development and production references;
+- CI workflow running the same canonical commands;
+- health endpoints;
+- a developer setup section in the implemented root README.
+
+## Dependency selection
+
+During Milestone 0, Codex verifies current stable compatible releases from primary sources, pins exact versions in the lockfile and records the selected runtime baseline. Avoid release candidates, betas and canary versions unless a required capability has no stable implementation and an ADR accepts the risk.
+
+Use one Node.js LTS line consistently across development, CI and container images. The container image must pin a specific immutable image tag or digest for release evidence.
+
+## Boundary enforcement
+
+Add automated dependency-boundary checks so:
+
+- UI cannot import database adapters directly;
+- route handlers call application use cases rather than persistence implementations;
+- domain packages do not depend on framework, HTTP or database packages;
+- integration adapters implement application ports;
+- content and composer code do not execute untrusted scripts;
+- worker jobs invoke idempotent use cases.
+
+## First vertical slice
+
+Before broad UI work, prove one end-to-end slice:
+
+1. start PostgreSQL, web and worker;
+2. complete first-run owner creation;
+3. import the 28 built-in packages;
+4. list packages through the API;
+5. open one package in a minimal UI;
+6. render the root-cause golden fixture through the production composer;
+7. compare bytes and digest with the reference fixture;
+8. store an immutable generated task;
+9. restart services and confirm persistence.
+
+This slice is the architectural proof. Do not postpone it until the final milestone.