Generated Artifacts Policy

Generated Artifacts Policy

This document defines where generated/output files belong and which generated files are intentionally versioned.

Goals

• Keep hand-written source visually distinct from machine-generated output.
• Prevent coverage/test/log/build artifacts from being recommitted.
• Make intentionally committed generated artifacts explicit and small in number.

Canonical locations

• App-consumed generated TypeScript (dashboard): apps/dashboard/src/generated/
• Repo-level committed generated planning/report artifacts: generated/
• Docs public generated OpenAPI payloads: apps/docs/public/openapi/
• Runtime/build/test output (non-source): ignored (coverage/, test-results/, dist/, build/, .wrangler/, .astro/, logs/)

Intentionally committed generated artifacts (allowlist)

• apps/dashboard/src/routeTree.gen.ts

  • Why kept: required by TanStack Router typed route generation.
  • Regenerate via: dashboard route generation workflow (dev/build).
  • Exception note: must remain source-adjacent due tooling constraints.

• apps/dashboard/src/generated/events/emitters.ts

  • Why kept: typed event helper surface consumed by dashboard code and CI drift checks.
  • Regenerate via: pnpm --filter @apps/dashboard events:generate.

• generated/eventbus/event-catalog.md

  • Why kept: generated catalog used in eventbus planning/verification context.
  • Regenerate via: pnpm --filter @apps/dashboard events:generate.

• apps/docs/public/openapi/*.json

  • Why kept: public docs site serves these as machine-readable API assets.
  • Regenerate via: pnpm --filter @apps/docs generate:api.
  • Exception note: remains under docs public/ because URL stability (/openapi/*.json) is intentional.

Must not be committed

• Coverage output
• Test-result output
• Build output
• Wrangler/Miniflare local state
• Logs
• Ephemeral state snapshots (for example, maestro active-session.md)

Operational guardrails

• If a generated artifact is consumed by product/docs code, keep it in an explicit generated location and document its regeneration command.
• If an artifact is reproducible and not consumed at runtime, delete it and rely on ignore rules.
• Prefer introducing a dedicated generated directory rather than writing generated files into feature/source folders.