# Repository operating contract ## Mission and source of truth - Product outcome: `<>` - Architecture: `<>` - Product decisions: `<>` - Delivery evidence: `<>` - Security/privacy baseline: `<>` - Runbooks: `<>` If code, docs, generated artifacts, and external contracts disagree, report the conflict. Do not silently choose the easiest interpretation. ## Repository map - `<>`: `<>` - `<>`: `<>` - `<>`: `<>` Keep domain rules separate from provider/UI adapters. Name generated and vendored directories that must not be edited manually. ## Exact commands Run commands from `<>`. - Install: `<>` - Development: `<>` - Format check: `<>` - Lint: `<>` - Typecheck/build: `<>` - Unit tests: `<>` - Integration tests: `<>` - E2E/revenue-critical tests: `<>` - Security/dependency check: `<>` - AI eval: `<>` Do not claim a check passed without running the exact applicable command. Report command, exit status, failed/skipped/flaky cases, and environment limitations. ## Durable invariants - Every tenant-owned read and write is server-side scoped to the authenticated tenant; never trust a client-provided tenant ID by itself. - Billing, webhook, job, and external write handlers are idempotent and preserve an append-only audit key. - Secrets, credentials, payment data, and unnecessary customer content never enter source, logs, analytics, fixtures, prompts, or screenshots. - Public API/event names and persisted schemas do not change without an explicit compatibility and migration plan. - Production side effects use test credentials or a sandbox during development; never send, charge, publish, delete, or mutate production data without explicit authorization. - `<>` ## Change triggers - Important architecture, provider, public contract, or irreversible choice: create/update an ADR. - New trust boundary, permission, sensitive data flow, dependency, external write, or migration: update the threat-model delta. - Behavior or AI configuration change: map acceptance criteria to tests/eval cases and record an exact evidence snapshot. - Production change: record immutable artifact, rollout, monitors, stop conditions, rollback class, owner, and post-release observation time. - Runtime identity/IAM, DB role/RLS/grants, credential ID-version-scope, egress, or autonomous trigger change: bind intended authority in review/deploy manifests and verify the actual authority receipt before enabling ingress/effects. - Auth/tenant/billing/personal-data/migration/privileged-CI/important-dependency/AI-tool-effect/rollback-weakening paths: derive at least R2 and required evidence from the semantic manifest. An applicable trigger's minimum tier/evidence is non-waivable. A lower reclassification is allowed only after positive evidence proves a false positive or the triggering scope is removed and the scan is rerun; owner approval alone is insufficient. Use `<>` and keep the same `change_id` across evidence within one delivery bundle. An incident always opens a new response `change_id` and links `originating_change_ids` plus affected release manifests. ## Scope and change discipline - One task produces one coherent customer or operational outcome. - Preserve unrelated user changes and do not reformat, rename, refactor, or add dependencies outside the stated scope. - New production dependencies require identity, maintenance, license, install-script, transitive-risk, size/cost, and removal-path review. - Changed or release-relevant privileged producer/consumer/deployer jobs require trigger, actor/ref trust, runner, token permissions, secret/OIDC, network/write targets, and artifact handoff review. Never combine untrusted code/artifacts with a privileged context. - Do not modify migrations, auth, billing, tenant boundaries, public APIs, policy, or production configuration as an incidental fix. - If an assumption changes the requested outcome or risk boundary, mark it `UNKNOWN` and surface it before proceeding. ## Verification by impact | Changed area | Required minimum evidence | |---|---| | Pure domain rule | unit/property tests including boundary and counterexample | | DB/query/migration | integration, tenant-negative, forward migration, reconciliation, rollback/compensation evidence | | API/webhook/job | contract, auth/signature, duplicate, reverse-order, retry/timeout tests | | UI | loading, empty, error, permission, keyboard/accessibility, responsive behavior | | Billing | signature, idempotency, amount/currency/tax, failure/recovery, cancellation/refund | | AI model/prompt/retrieval | frozen cases/splits/versions, critical failures, x/n and unknown, cost/latency | | Tool action | exact approval, target/args, post-condition, duplicate execution, cancel/rollback | | Operations | metrics/logs without secrets, alert action, runbook, stop and recovery verification | Select applicable rows and explain exclusions. A checkbox is not evidence. ## Code Review Rules ### Tenant isolation - Flag any tenant-owned query or cache key that can execute without server-derived tenant scope. Safe path: derive tenant context from the authenticated session and test another-tenant IDs return no data and make no mutation. ### External effects - Flag send/pay/publish/delete/write paths that lack an idempotency key, bounded authority, audit event, and verified post-condition. Safe path: separate propose from commit, require exact approval where appropriate, and make retry safe. ### Compatibility - Flag removal or rename of documented public APIs, events, fields, persisted values, or migrations without a compatibility plan. Safe path: preserve the old contract during a measured migration or version the interface. ### Customer data - Flag logs, fixtures, prompts, analytics, or errors that add credentials, payment data, personal data, or unnecessary customer content. Safe path: minimize, redact, use synthetic fixtures, and record controlled artifact references instead of raw content. ## Definition of done - The stated behavior and non-goals match the diff. - Every applicable `AC-*` points to current evidence for the exact commit. - Test/eval results have one immutable `EVID run manifest`; PR and release refer to its hash instead of retyping PASS counts. - Reviewed head, merge/source tree, build provenance, artifact, schema/intended config/tool policy, IaC, runtime identity/IAM, DB role/RLS/grants, credential ID-version-scope, and egress reach an approved deploy manifest before suspended stage-0 deploy. - A trusted upstream fence receipt disables candidate traffic/webhook/queue/cron/startup/tool-effect surfaces before the candidate starts; customer exposure 0 alone is insufficient. - The actual runtime/authority receipt matches that deploy manifest and reaches a separately approved promotion manifest before any candidate ingress/effect is enabled or released/exposed. - Every enable/expansion has a trusted activation receipt whose actual cohort, ingress/effect capability, controller version, and residual fences match the fresh approval before the stage is considered active. - Relevant format, type, lint, test, security, eval, and generated-diff checks pass; failures/skips/unknowns are disclosed. - Data, permission, privacy, cost, dependency, compatibility, migration, observability, and rollback impacts are reviewed. - User-visible behavior, API, operations, or decisions update the corresponding documentation/runbook. - No required `STOP`, `PAUSE`, or `UNKNOWN` remains before a `SHIP` decision. - The final handoff lists changed files, evidence, remaining risk, and next observation time. Codex completion is not production authorization. Merge, deploy, exposure, risk acceptance, and destructive/external actions remain subject to repository controls and accountable human approval.