agentic-dev/CLAUDE.md

# Veect — Control-Plane Monorepo

## Quick Start

```bash
pnpm install                # Install + auto-wire husky pre-commit hooks
pnpm dev                    # Start all dev servers
pnpm build                  # Build all packages
pnpm test                   # Run all tests
pnpm typecheck              # TypeScript across all packages
pnpm lint                   # ESLint (incl. 16 conformance/* rules)
pnpm conformance            # Cross-feature event closure
pnpm fallow                 # Whole-codebase: dead exports, dupes, complexity
pnpm fallow:audit           # AI-change audit (run before commits)
pnpm coverage:aggregate     # Merge per-package lcovs -> coverage/lcov.info + summary.json (L2)
pnpm coverage:diff          # Cover-the-diff gate; JSON to stdout (L1, ADR-020)
pnpm mutate                 # Stryker mutation testing on entities + use-cases (L3, on-demand)
pnpm turbo boundaries       # Workspace dependency graph
pnpm work status            # docs/work/ epic + story state
pnpm work next              # Next ready story
pnpm work dispatch          # Print next dispatch plan (use --execute to invoke sandcastle)
pnpm turbo gen feature      # Scaffold a new feature package
pnpm turbo gen event        # Scaffold an event contract or handler
pnpm turbo gen job          # Scaffold a background job
pnpm turbo gen realtime     # Scaffold a realtime channel or handler
pnpm turbo gen reader       # Scaffold a cross-feature reader
pnpm turbo gen core-package # Scaffold an optional core package
pnpm turbo gen core-ui-component # Scaffold an atomic-design component
docker compose up -d        # Start PostgreSQL
```

**First time?** Read [`docs/guides/runbook.md`](./docs/guides/runbook.md) end-to-end.

## TDD

```bash
pnpm test --watch --filter @repo/<feature>   # watch one feature
pnpm test:coverage                           # full run with coverage
pnpm test:stories                            # Storybook smoke tests
pnpm test:e2e                                # Playwright e2e
```

See `docs/guides/tdd-workflow.md` for the full cycle.

## Project Overview

**Veect** (pronounced VEEKT) is a hosted design-to-code SaaS: it connects to a team's code repository, discovers the repo's real components and design tokens, lets a designer compose screens on a canvas constrained to that system, and publishes real TSX as an ordinary pull request. The authoritative product spec bundle lives in `docs/product/` — read `docs/product/README.md` first; it defines which document wins when two disagree. Where the bundle conflicts with the repo's ADRs, the ADRs win:

- **ADR-027** — Veect v1 is a hosted cloud SaaS split into a **control plane** (this monorepo: auth, tenancy, workspace/project metadata, design-doc persistence, AI proxying, runner orchestration) and **workspace runners** (**cloud runner**: one isolated container per workspace; **local runner**: a CLI the developer runs against a local checkout), joined by a single **runner protocol**.
- **ADR-028** — the **iframe canvas**: the board renders real repo components through runner-served iframes (preview adapter + injected agent script over postMessage). NodeRenderer survives only in the **Playground** (the no-repo sandbox).
- **ADR-029** — **DesignDoc v1** (`design.veect.json`) is the canonical committed schema; the editor is rebuilt under template conventions. **Checkpoint** (codegen → parity check → atomic commit on the project branch) and **publish** (push branch + PR link) are the two git verbs.

Veect-domain vocabulary (control plane, workspace, project, runner, registry, iframe canvas, Playground, checkpoint, publish, …) is canonical in `docs/glossary.md` § "Veect product domain" — it wins over the product docs where they disagree.

**Repo shape:** Turborepo + pnpm monorepo organized by vertical features. One feature package so far (`auth`) owns its Clean Architecture layers; the Veect control-plane features (workspaces, projects, discovery, design-doc, editor, …) follow the same shape. Must-have core packages (`core-shared`, `core-cms`, `core-api`) provide foundation; eight optional cores are scaffolded and present (`core-trpc`, `core-ui`, `core-events`, `core-realtime`, `core-audit`, `core-analytics`, `core-consent`, `core-dsr`); new ones scaffold via `pnpm turbo gen core-package <name>` (see `docs/architecture/template-tiers.md`). Three tooling packages (`core-eslint`, `core-typescript`, `core-testing`) provide shared configs and test utilities. Three apps: `apps/web-next` (Next.js — the hosted editor shell + landing page), `apps/cms` (Payload admin), `apps/storybook`. Control-plane persistence is Payload CMS + Postgres (ADR-027). Workspace boundaries are enforced by ESLint (lint-time) and Turborepo (build-graph time).

## Read First

- `docs/glossary.md` — **Canonical vocabulary** for the monorepo, including the "Veect product domain" section (control plane, runner, runner protocol, iframe canvas, Playground, checkpoint, publish, …). Resolves "what does X mean here?" for every cross-cutting term. Shared between humans and agents.
- `docs/product/README.md` — Entry point to the authoritative product spec bundle in `docs/product/` (tech spec, design spec, UI gap spec, PRD, strategy docs) and the authority table for when documents disagree — as amended by ADR-027/028/029
- `docs/decisions/adr-027-hosted-saas-and-runner-split.md` — hosted SaaS topology: control plane / workspace runners / runner protocol
- `docs/decisions/adr-028-iframe-canvas.md` — the one-runtime invariant on the board; canvas protocol; Playground boundary
- `docs/decisions/adr-029-designdoc-v1-and-editor-rebuild.md` — DesignDoc v1 committed schema; editor rebuilt under template conventions
- `AGENTS.md` — Package map, boundary rules, per-package conventions
- `docs/architecture/overview.md` — High-level architecture and package responsibilities
- `docs/architecture/vertical-feature-spec.md` — Design spec with rationale and decision log
- `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path; prefer this over the manual walkthrough)
- `docs/guides/adding-a-feature.md` — End-to-end new feature walkthrough (manual path; for cases the generator's scope doesn't cover)
- `docs/guides/events-and-jobs.md` — publish/consume/schedule cookbook (cross-feature events + background jobs; `core-events` is scaffolded in this repo)
- `docs/guides/realtime.md` — Socket.IO channels, broadcasts, handlers (`core-realtime` is scaffolded in this repo)
- `docs/guides/audit-and-compliance.md` — DPA-compliant audit logging cookbook (`core-audit` is scaffolded in this repo)
- `docs/guides/coverage.md` — 4-layer coverage cookbook (L0 vitest thresholds, L1 `pnpm coverage:diff`, L2 aggregate, L3 mutation; ADR-020)
- `docs/guides/releasing.md` — release-please workflow: how Conventional Commits become the single root product version + `CHANGELOG.md`, tagged `v*` (ADR-021, root-only since the ADR-027 retrofit)
- `docs/architecture/template-tiers.md` — must-have vs optional packages and how to scaffold the optionals
- `docs/guides/building-feature-ui.md` — Feature UI components, hooks, data fetching (tRPC + React Query), SSR prefetch/hydration, seed data, DI wiring
- `docs/guides/compliance-overview.md` — hub for operator compliance obligations: GDPR, cookie consent, DSR, and pre-launch checklist

## Conformance system

Every feature has a `src/feature.manifest.ts` declaring its use cases, audits, publishes, consumes, reads (cross-feature reader deps), required cores, `rateLimit?: RateLimitBudget[]` (when applicable, for per-use-case rate-limit budgets), and (when applicable) `requiresConsent: ConsentCategory[]` for features that gate behaviour behind user consent. Drift is caught at five latencies:

| Layer                                  | Latency | Catches                                                                                                     |
| -------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| **TypeScript brands**                  | 0s      | forgotten `withSpan` / `withCapture` / `withAudit` at bind time                                             |
| **ESLint rules**                       | <1s     | manifest ↔ code drift; undeclared `bus.publish` / `auditLog.record`; missing manifest; missing sibling test |
| **Boot assertion** (`pnpm dev`)        | ~3s     | binding without required brand at runtime; manifest edited without rebinder                                 |
| **CI drift gate** (`pnpm conformance`) | ~120s   | orphan event consumers across features                                                                      |
| **Fallow** (`pnpm fallow`)             | ~30–60s | dead exports / unused files; duplicate code; circular deps; complexity hotspots; AI-change audit drift      |

The sixteen conformance ESLint rules: `feature-must-have-manifest` (error), `usecase-must-have-test-file` (error), `required-cores-installed` (error), `usecase-must-be-wired` (error), `no-undeclared-event-publish` (warn), `no-undeclared-audit` (warn), `no-undeclared-analytics-event` (warn), `no-undeclared-reader` (warn), `pii-declaration-must-be-complete` (warn), `component-must-have-story` (warn), `component-must-have-test` (warn), `atomic-tier-import-direction` (warn), `no-undeclared-consent-check` (warn), `no-undeclared-rate-limit` (warn), `entity-must-have-test` (warn), `no-relative-parent-import-in-tests` (warn). Fallow runs as a fifth layer, post-ESLint, whole-codebase.

See `docs/architecture/agent-first-workflow-and-conformance.md` for the full design and `docs/guides/conformance-quickref.md` for the day-to-day reference.

### Sibling architecture: coverage (ADR-020)

Coverage runs in parallel to the 5-gate conformance system above — same multi-latency philosophy, different signal. Each feature's `feature.manifest.ts` declares a `coverage.bands` section that vitest (test-time), `pnpm coverage:diff` (CI/agent-loop), and `pnpm mutate` (nightly) all read from. Four layers:

| Layer                              | Catches                                                             | Surface                                                       |
| ---------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
| **L0** Per-layer vitest thresholds | Drift below declared bands (entities/use-cases/controllers at 100%) | `pnpm test:coverage`                                          |
| **L1** Diff coverage               | Changed line not exercised by tests                                 | `pnpm coverage:diff` — CI-gated on PRs + dispatch post-task   |
| **L2** Aggregate trend             | Codebase coverage drifted over time                                 | `pnpm coverage:aggregate` → committed `coverage/summary.json` |
| **L3** Mutation testing            | Tests that exist + execute the code but assert nothing              | `pnpm mutate` — on-demand + nightly GH Action                 |

See `docs/guides/coverage.md` for the cookbook and ADR-020 for the full rationale. Agents running in sandcastle: run `pnpm coverage:diff` before reporting `complete` — the implementer and reviewer prompts enforce this.

## Key Conventions

- **Conventional Commits (non-negotiable)** — Every commit message MUST follow the [Conventional Commits](https://www.conventionalcommits.org/) spec: `<type>(<scope>): <imperative subject>` (≤72 chars). Types: `feat | fix | docs | style | refactor | test | chore | perf | ci | build | revert`. Use `!` after type/scope for breaking changes. Body explains WHY if non-obvious. Examples: `feat(auth): hash password before persisting`, `test(auth): assert invalid credentials error`, `refactor(docs)!: consolidate scaffolding into guides`. The sandcastle implementer + reviewer prompts both enforce this; agents authoring commits autonomously MUST honor it. Commits become versions + changelog entries automatically via release-please (ADR-021 / `docs/guides/releasing.md`).
- **Versioning is root-only (ADR-021, amended by the ADR-027 retrofit)** — Veect is a hosted SaaS deploying continuously, so release-please tracks a **single root product version** from `0.1.0` with plain `v*` tags (`include-component-in-tag: false`). It reads Conventional Commits since the last tag and opens a rolling release PR on every merge to main; merging it cuts the tag (`v0.2.0`) + GitHub release + root `CHANGELOG.md`. Every commit path bumps the root — there are no per-package versions or tags. Pre-1.0 policy: `feat:` → patch, `feat!:` → minor.
- **Relative imports in `src/`** — Source files use relative paths (`../repositories/...`), not `@/` alias
- **`@/` alias in tests** — Test files (`*.test.ts`) use `@/` to import from `src/`
- **`vitest.config.ts`** — Every package must define `resolve.alias: { "@": path.resolve(__dirname, "./src") }`
- **`tsconfig.json` rootDir** — Set `"rootDir": "."` so TypeScript finds both `src/` and test files
- **File layout convention** — Entities live at `entities/models/<x>.ts`; errors at `entities/errors/<domain>.ts` + `entities/errors/common.ts`; mock siblings use the `.mock.ts` suffix (`<x>.repository.mock.ts`); real repository impls drop the `payload-` prefix (`<x>.repository.ts`); interface filenames are dot-separated (`<x>.repository.interface.ts`)
- **Factory-function use cases & controllers** — Every use case and controller is `(deps) => async (input) => result`; each exports `export type I*UseCase = ReturnType<typeof xUseCase>` (and the analogous `I*Controller`); one controller per use case (no multi-method controllers)
- **DI uses `.toDynamicValue()` for factories** — `bind<IXUseCase>(SYMBOL).toDynamicValue((ctx) => xUseCase(ctx.container.get(...)))`; mocks remain the default binding
- **Tests inject mocks directly** — Construct `MockXRepository` and pass into the factory: `signInUseCase(mockUsers, mockAuth)(input)`. No container rebinding in unit tests
- **Schemas in the use-case file** — Every use case exports `xInputSchema` (a `z.ZodObject` with `.strict()`; `z.object({}).strict()` for void inputs) and, for non-void use cases, `xOutputSchema`. Types: `XInput = z.infer<typeof xInputSchema>` and `XOutput`. Use case body ends with `xOutputSchema.parse(result)` before returning (runtime guarantee against malformed repository data)
- **Controllers receive `unknown` + presenter** — Controllers `safeParse(xInputSchema)` from the use-case file and throw `InputParseError` on failure. Non-void controllers define a top-level `function presenter(value: XOutput)` and return `Promise<ReturnType<typeof presenter>>` (identity is fine — `return value`); void controllers return `Promise<void>` with no presenter
- **Feature-scoped tRPC error mapping** — Each feature has `integrations/api/procedures.ts` exporting `xProcedure = t.procedure.use(defineErrorMiddleware([[Ctor, "TRPC_CODE"], ...]))` from `@repo/core-shared/trpc/define-error-middleware`. Routers use `xProcedure.input(xInputSchema)` — schemas are imported from the use-case file, never redefined inline. `core-shared` never enumerates feature error classes
- **Public surface split** — Feature root (`.`) exports contracts only: types, errors, schemas, IUseCase / IController aliases, router type, constants. UI artifacts (hooks, components, query builders) live behind `./ui` (`src/ui/index.ts`). Apps import hooks/components from `@repo/<feature>/ui`, schemas/types from `@repo/<feature>`
- **Feature UI owns its data fetching** — Each feature's `src/ui/hooks/` contains `"use client"` hooks that wrap `useTRPC` + `useSuspenseQuery`. Connected components in `src/ui/components/` call these hooks. App pages prefetch via `appRouter.createCaller({})` and hydrate via `HydrationBoundary` + `dehydrate` + `setQueryData`. See `docs/guides/building-feature-ui.md`
- **Payload repositories via constructor** — Feature packages receive Payload config at constructor time, not as a direct dependency
- **Three binding modes per feature** — Each feature exports two binders: `./di/bind-production` (real Payload) and `./di/bind-dev-seed` (populated mock). The app's `bindAll()` dispatcher in `apps/web-next/src/server/bind-production.ts` picks one by env: `USE_DEV_SEED="true"` → dev seed; `NODE_ENV="production"` → production; otherwise → dev seed (developer default so `pnpm dev` boots without Payload). Dev seed lives in `src/__seeds__/dev.ts` as a lazy `buildDev<Entities>()` function that uses the feature's existing factory
- **Binders take a `ctx` arg from `core-shared/di`** — `bindProductionX(ctx: BindProductionContext)` for production binders; `bindDevSeedX(ctx: BindContext)` for dev-seed. Required fields: `tracer`, `logger`, plus `config` for production. Optional fields: `bus`, `queue`, `realtime`, `realtimeRegistry` (correspond to optional core packages — guard with `?.` or `if (bus) { ... }` when used; use-case signatures should accept the protocol type when they only need protocol methods, not the full concrete interface). Aggregator builds one ctx object and passes it to all feature binders
- **App bootstrap** — Each app calls `bindAll()` from a server entry point (page server component, route handler) before resolving any feature controller. The dispatcher is idempotent
- **Instrumentation lives in `core-shared/instrumentation/`** — Three interfaces (`ITracer`, `ILogger`, `IMetrics`), three implementation pairs (`Noop*`, `Otel*`, and `Recording*` from `core-testing`). The OTel SDK is the substrate; Sentry is wired as the exporter via `@sentry/opentelemetry`. Feature packages MUST NOT import `@opentelemetry/sdk-*` or `@sentry/*` directly (ESLint-enforced); the vendor-neutral `@opentelemetry/api` family is the import surface for advanced cases (ADR-017)
- **Spans + capture composed at DI bind time** — Use cases + controllers are wrapped at DI bind time in this order (outermost → innermost): `withSpan → withCapture → withAudit → withAnalytics → withConsent → factory(deps)`. Apply `withAudit` when the manifest declares `audits`, `withAnalytics` when it declares `analyticsEvents`, `withConsent` when it declares `requiresConsent`. `withSpan` is always outermost so an errored span's timing reflects the capture-and-rethrow. Repository methods are different — they call `this.tracer.startSpan(...)` and `this.logger.captureException(...)` inline per method because they own per-call attributes
- **Capture at throw sites only, with double-report guard** — Repos capture infra errors inline; use cases + controllers capture via `withCapture` at bind time; `defineErrorMiddleware` never captures. Each error gets a non-enumerable `__sentryReported` flag the first time it's captured; `withCapture`, `OtelLogger`, and `RecordingLogger` all bail if the flag is set, so a bubbled error surfaces exactly once with the inner-most layer's tags (helper at `core-shared/instrumentation/reported-flag.ts`)
- **PII handling is non-negotiable** — `sendDefaultPii: false` everywhere (CI grep gate); replay default-masks all text/inputs/media (allowlist starts empty); `setUser({ id })` only — no email/username; server-side PII scrubbing happens at the OTel processor layer (`PiiScrubSpanProcessor` + `PiiScrubLogRecordProcessor`) before any exporter sees the data (ADR-017 §7)
- **Two Sentry projects** — `WEB_NEXT_SENTRY_DSN`, `CMS_SENTRY_DSN` (storybook is not instrumented). The browser DSN uses the `NEXT_PUBLIC_` prefix (web-next)
- **Instrumentation binding is orthogonal to repo binding** — `bindAll()`'s Rule 0 (DSN → OTel+Sentry vs Noop) is independent of `USE_DEV_SEED` / `NODE_ENV`. Run `pnpm dev` with `WEB_NEXT_SENTRY_DSN` set to test the integration locally
- **Cross-feature events go through `IEventBus` (E0)** — In-feature reactions are direct use-case calls, not bus publishes. The bus is for _crossing_ feature boundaries (e.g. an `auth` signed-up event consumed by another feature)
- **Event contracts are public; handlers are private (E1)** — Publisher's `events/<x>.event.ts` is exported from the feature root barrel. Consumer's `events/handlers/on-<publisher>-<event>.handler.ts` is never re-exported (ESLint-enforced via `core-eslint/rules/no-handler-reexport`)
- **Jobs are for _deferred_ work, not abstraction (J0)** — Synchronous code stays synchronous. A job exists only when something must run off the request path (latency, retries, cron). Feature packages enqueue via `IJobQueue` only — direct `payload.jobs.queue()` is ESLint-blocked outside `core-shared/jobs/`
- **Realtime is for state delivery, not for replacing tRPC (R0)** — Persistent request/response operations belong on tRPC procedures. Use realtime when the server needs to push without a request or the data is too high-frequency for HTTP
- **Realtime channel descriptors are exported; handlers are private (R1)** — A feature's `realtime/<name>.channel.ts` is re-exported from the root barrel; `realtime/handlers/*.handler.ts` is wired only in bind-\* files and never re-exported (ESLint-enforced via `no-realtime-handler-reexport`)
- **`socket.io` lives in `@repo/core-realtime` only (R2)** — Feature packages MUST NOT import `socket.io` or `socket.io-client`. ESLint rule `no-direct-socket-io` enforces this; allowlist covers `core-realtime/src/socket-io-*.ts` and `apps/*/server.ts`
- **Cross-feature domain queries go through readers (Q0)** — When a use case needs another vertical's domain-evaluated answer on the request path (e.g., permission check), use a reader (`I<Feature>Reader`). For raw data joins, use Payload `relationTo`. For reactions/side effects, use the event bus
- **Reader contracts are public; implementations are private (Q1)** — The owning feature exports `I<Feature>Reader` from `./reader` subpath (`integrations/readers/`). The implementation (`<Feature>Reader`) is internal, constructed by the binder. Consumers import the type only
- **Readers are strictly read-only; cross-feature writes go through events (Q2)** — A reader may only wrap use cases declared `mutates: false`. Enforced by `ReadOnly<F>` brand at compile time and `assertReaderPurity` at boot time
- **Reader cycles are a design error (Q3)** — If Feature A reads from Feature B and vice versa, the boundaries are wrong. Break via: (a) UI composition at app layer, (b) event for one direction, (c) merge the features
- **Readers wrap existing use cases, not repositories** — The reader is a thin facade; if the domain logic doesn't exist as a use case yet, create the use case first (manifest-first). No `MockReader` needed — same class works in dev-seed because the use cases beneath it are backed by mock repos
- **Manifest `reads` field** — Use cases that query another feature's reader declare `reads: ["<feature>"]` in `feature.manifest.ts`. Verified by `assertFeatureConformance` at boot and `no-undeclared-reader` ESLint rule
- **Binders return readers; `bindAll()` threads them** — `bindProductionAuth(ctx)` returns `{ reader: IAuthReader }`. `bindAll()` passes it: `bindProductionX(ctx, { authReader: authResult.reader })`. Ordering in `bindAll()` is explicit — owning feature first, consumers after
- **Manifest-first ordering** — for any new use case, the workflow is **(1) manifest entry** → **(2) contracts** (`xInputSchema`, `xOutputSchema`, `IXUseCase`) → **(3) tests (red)** → **(4) implementation (green)**. The generator emits the manifest + a self-asserting `bind-production.ts` so new features are conformance-compliant by default
- **Self-asserting `bindProductionX(ctx)`** — every feature's bind-production calls `assertFeatureConformance(container, manifest, symbols, ctx)` at its tail. `pnpm dev` refuses to boot on drift
- **`pnpm conformance`** — cross-feature event-closure and reader-closure check; fails CI on orphan consumers or unresolvable `reads` entries
- **New runtime dependencies require a library trace** — adding a runtime dependency to a feature- or core-tier package requires a trace at `docs/library-decisions/<date>-<name>.md` produced by the `/evaluate-library` skill; see ADR-022 and `docs/guides/adding-a-library.md`
- **CI security + supply-chain enforcement** — Renovate for bumps + Action SHA pinning, Socket for supply-chain behavior, weekly trace revalidation, CodeQL + audit signatures + gitleaks. See ADR-023 + `docs/guides/ci-security.md`

## MCP Servers

Start Storybook before UI work: `pnpm dev --filter @repo/storybook`

Storybook MCP available at `http://localhost:6006/mcp` — use `list-all-documentation` to discover existing components before creating new ones.

## Key Ports

| Service     | Port |
| ----------- | ---- |
| Next.js     | 3000 |
| Payload CMS | 3001 |
| PostgreSQL  | 5432 |
| Storybook   | 6006 |