Working on GuestCraft

Read CONTRIBUTING.md, the package README and the relevant architecture rules and ADRs before changing code. These are repository instructions for every contributor and agent. An explicit user instruction takes precedence; report any resulting limitation.

Product work

• Define observable acceptance criteria before implementing a feature. Identify the objects, operations, permissions and screens the user must actually use.
• Deliver a coherent workflow across the relevant domain rules, migrations, repositories, public API, OpenAPI, SDK and UI. A backend-only change may be intentional, but must be reported as partial product functionality.
• A type, SQL table, reusable component, simulator, API client or design document does not make an operator workflow complete. A verified Channex connection does not imply import, mapping, reservation intake or inventory synchronization.
• Keep implemented, partial and planned capabilities distinct in documentation, developer contracts and completion reports. Never use coverage or test counts as a product-completion percentage.
• Test the complete supported workflow, including reload/persistence, denied access, invalid input and recovery. Use real database integration tests where persistence or isolation matters, and the built application for browser checks.

Code boundaries

• Keep the domain independent of infrastructure. Wire adapters in server and follow the dependency matrix; MIT packages cannot depend on AGPL packages.
• Use strict ESM TypeScript and the existing Result/error conventions. Inject time, randomness and identifiers into domain code. Read environment only at the documented composition boundaries.
• Use currency-aware minor units and Temporal stay dates. Preserve workspace and organization isolation, composite foreign keys, role grants and audit behavior.
• Keep language, currency, measurement units and country rules explicit. Use the shared i18n catalogs, locale-aware formatting and canonical identifiers; do not hardcode Italy, euros or one measurement system into domain workflows. National compliance belongs in country packs, outside the country-independent core.
• Never expose or commit real credentials, guest/card data, upstream bodies or sensitive values in logs, fixtures, action state or error messages.
• Add a new migration for schema changes; never edit an applied migration. Update inventory, grants, schema revisions, repositories and real PostgreSQL tests.

Tests and verification

• Fixes need a regression at the level where the failure occurs. Test behavior and invariants with independent expectations; avoid tests that mirror code or pad coverage. Documentation-only changes need appropriate documentation checks.
• PostgreSQL, RLS, transactions and PgBouncer are tested against real processes. External HTTP tests use injected transports or the independent Channex simulator. Do not require customer credentials in CI.
• Do not add .only or .skip, hide flaky failures, lower coverage, or exclude handwritten source to make a gate pass. Coverage thresholds live in vitest.config.ts; all handwritten source counts, imported or not.
• Run pnpm quality for code changes. It checks formatting/lint, boundaries, dead code, license direction, types and the complete test suite with coverage.
• Also run REUSE, commitlint and the relevant deployment build/contract checks as CI does. Regenerate OpenAPI and SDK when public contracts change, and verify committed artifacts are current. A new package needs explicit quality coverage.
• UI changes use semantic tokens and existing accessible components, the English catalog, field-linked errors and loading/empty/permission/failure states. Verify keyboard use and accessibility for the affected workflow.

Delivery

• Use focused PRs and Conventional Commits. Follow the PR checklist, owner-review rules and applicable DCO requirements in CONTRIBUTING.
• Merge only after the required CI checks pass. Do not bypass branch protection, force-push main, or claim a pending check passed.
• Report what changed, what was verified, and material remaining product gaps. Do not declare a PMS module finished from a scaffold or successful mock alone.