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

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:

start PostgreSQL, web and worker;
complete first-run owner creation;
import the 28 built-in packages;
list packages through the API;
open one package in a minimal UI;
render the root-cause golden fixture through the production composer;
compare bytes and digest with the reference fixture;
store an immutable generated task;
restart services and confirm persistence.

This slice is the architectural proof. Do not postpone it until the final milestone.

3.5 KiB Raw Blame History