Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

[!CAUTION] Pre-Alpha Trash Archive Warning

The code, architecture, and design patterns in this file are completely dead. To find what you actually need, go back to the active trefniq.com documentation site.

Repository Agent Rules — TrefnIQ current

Controlling files​

  • engineeringspec.md is the controlling product specification.
  • docs/engineering/workspace-boundaries.md is the controlling TrefnIQ monorepo-layout overlay.
  • Do not create engineering-spec.md.
  • Do not recreate eningeeringspec.md.
  • Do not rename engineeringspec.md.
  • Do not create wrangler.toml.
  • Do not create Cloudflare KV bindings in this build.
  • Do not create preview or staging D1/R2 resources unless a later ADR explicitly changes the scope.
  • Keep the R2 Worker binding as FILES_BUCKET.

Foundation state​

The repository is the TrefnIQ foundation-ready baseline. It includes the app shell, config package, shared package, database foundation, services stubs, Vitest tests, CI workflow and final workspace consistency validator.

Do not present the app shell, temporary cookie gate, static dashboard cards, foundation database schema or service stubs as completed SaaS product features. They are rails for feature development, not the finished product.

Workspace rules​

  • Root-level code should be limited to repository orchestration, configuration, documentation and validation scripts.
  • Application code belongs in apps/web.
  • Shared constants and environment validation belong in packages/config.
  • Framework-neutral utilities belong in packages/shared.
  • Drizzle/D1 schema and tenant-scope database helpers belong in packages/database.
  • External provider contracts and safe stubs belong in packages/services.
  • Directory names must remain lowercase.
  • Keep forceConsistentCasingInFileNames enabled.

Validation rules​

Before opening or completing any feature PR, run:

scripts/validate-foundation-readiness.sh
python3 scripts/validate-workspace-consistency.py
python3 scripts/validate-ci-workflow.py
python3 scripts/validate-d1-migrations.py

After dependencies are installed, run:

pnpm ci:verify

After real local values are added, run:

scripts/validate-foundation-readiness.sh --strict-secrets

Environment and secret rules​

  • Do not commit .env, .dev.vars, .env.* or .dev.vars.*, except .env.example and .dev.vars.example.
  • Do not expose secret values in browser code, service health checks, logs or tests.
  • Use the TrefnIQ environment validation package rather than direct unchecked environment access.
  • Stripe must remain sandbox/test-mode only for this build.
  • Do not reintroduce legacy environment names such as STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, NEXT_PUBLIC_GOOGLE_MAPS_BROWSER_API_KEY, GOOGLE_MAPS_SERVER_API_KEY, NRW_API_KEY or EA_API_KEY.
  • PR-04D customer-app auth uses TrefnIQ Edge Auth under /auth/* with opaque D1-backed sessions. Cloudflare Access is admin-only for admin.trefniq.com/* and must not be restored as a customer-app fallback.

Database rules​

  • The foundation schema is not the full canonical SaaS schema.
  • Expand the schema from engineeringspec.md in controlled migrations.
  • Keep tenant scoping explicit.
  • Keep audit events append-only unless a later ADR defines a stronger audit architecture.
  • R2 object metadata belongs in D1; do not use KV for file metadata.

Services rules​

  • Provider stubs in packages/services must remain side-effect safe.
  • Live provider implementations must preserve the typed interfaces unless a later ADR changes them.
  • Do not add live provider calls without timeout controls, structured errors, test coverage and audit/logging rules.

Testing rules​

  • Keep foundation tests side-effect safe.
  • Do not add .only focused tests.
  • Do not call live external networks, Stripe, email providers, AI providers, R2 or flood APIs from foundation tests.

CI rules​

  • The foundation CI workflow must remain validation-only until a dedicated deployment milestone.
  • Do not add deployment commands, upload commands, provider API calls or GitHub secret access to CI without a later explicit deployment scope.

Handoff principle​

Build forward from the foundation. Do not flatten, replace or bypass the foundation because it feels faster. That is how repos become archaeological sites with TypeScript.