PROJECT_CONSTITUTION.md

Project Constitution

This constitution defines non-negotiable rules for OpenInvoice. It is a Tier 1 baseline document. The current version is draft and is not approved until explicitly accepted by the human Architecture Owner.

Constitutional rules

CONST-001 - Product identity

The approved working product name is OpenInvoice. AI and contributors must not rename, abbreviate, rebrand, or replace the product without explicit human approval.

CONST-002 - Workspace isolation

A workspace must never silently read, write, execute, report on, or expose another workspace's customers, custom fields, invoice definitions, templates, dynamic data, assignments, runs, jobs, attempts, retries, reports, statistics, audit events, files, or settings.

CONST-003 - Explicit ownership

Every workspace-owned operation and persisted record must carry explicit workspace scope. Global mutable “current workspace” state must not be the sole authorization or routing mechanism.

CONST-004 - Domain separation

Workspace, Run, Job, and Attempt are separate domain concepts. They must not be collapsed into one oversized task entity.

CONST-005 - Immutable execution snapshots

A run must execute from an immutable snapshot of the approved workspace configuration. Editing workspace configuration must not alter an already-started run.

CONST-006 - Durable execution

Authoritative job state must be persisted. In-memory queues or UI state must not be the sole source of truth for work awaiting execution or recovery.

CONST-007 - Explicit state transitions

Run, Job, and Attempt state changes must be explicit, validated, auditable, and recoverable. Unknown external outcomes must not be reported as success or blindly retried.

CONST-008 - Idempotency and reconciliation

External provider operations must carry idempotency context where supported. When the result of an external operation is uncertain, reconciliation must occur before a duplicate operation is attempted.

CONST-009 - Bounded execution

Execution concurrency must remain bounded globally and by relevant provider, account, endpoint, and operation limits. A user-facing “fastest” choice must never disable safety limits.

CONST-010 - Global physical-account coordination

Physical account health, quotas, cooldowns, and provider-wide limits must be coordinated globally even when an account is assigned to multiple isolated workspaces.

CONST-011 - Secure secret handling

Credentials, access tokens, private material, and equivalent secrets must not be stored in plaintext SQLite databases, ordinary configuration files, logs, update packages, or diagnostics bundles. Secure storage failure must not silently fall back to plaintext.

CONST-012 - UI separation

UI components must not directly access databases or call provider APIs. Workers and provider executors must not update Tkinter widgets directly. UI updates must pass through a thread-safe application event boundary.

CONST-013 - Provider abstraction

Provider-specific behavior must remain behind capability-based adapter contracts. The core domain and UI must not assume every provider supports the same operations.

CONST-014 - Beginner-oriented workflow

The default experience must be workflow-oriented and use plain language, progressive disclosure, safe defaults, preflight review, and visible status. Technical diagnostics must remain separate from the standard workflow.

CONST-015 - Auditability

Security-sensitive changes, external operation outcomes, account assignments, run lifecycle events, recovery decisions, and report exports must be traceable without exposing secrets.

CONST-016 - Documentation governance

A change is not merge-ready until its documentation impact is assessed. Required documentation must be updated in the same reviewed change or explicitly declared unaffected with a reason.

CONST-017 - Evidence-based quality claims

No contributor or AI may claim that tests, validations, packaging, security checks, migrations, or recovery scenarios passed without recorded evidence from an actual execution.

CONST-018 - Quality gates

Required static analysis, tests, architecture checks, migration checks, security checks, and human review must not be disabled or bypassed to obtain a merge or release.

CONST-019 - AI authority boundary

AI may analyze, draft, implement approved bounded work, test, review, and propose alternatives. AI may not approve architecture changes, silently alter the baseline, invent requirements, introduce unapproved dependencies, overwrite unrelated work, expose secrets, or push directly to protected branches.

CONST-020 - Human approval authority

Only the human Architecture Owner may approve the architecture baseline, ADR acceptance, ACR disposition, or a constitutional change. Only the designated human Final Approver may authorize phase acceptance and release.

CONST-021 - Architecture change control

When an approved requirement conflicts with the approved baseline, implementation of the conflicting path must stop. The conflict must be recorded and an ACR must be drafted for explicit human review.

CONST-022 - Repository preservation

Update packages must include only new or modified files and preserve repository-relative paths. They must not replace the whole repository, delete unrelated files, include .git, or overwrite unrelated user changes.

Enforcement

Future engineering phases must translate applicable constitutional rules into architecture fitness tests, repository rules, pull-request checks, and release gates.

Approval status

• Drafted: Yes
• Phase 0A gate review: Completed
• Complete baseline approved: No

Phase-gate status

• Phase 0A documentation and governance gate: Approved on 2026-07-23
• Complete production constitution and architecture baseline: Draft
• Phase 0B technical evidence collection: Authorized
• Final baseline approval authority: Human Architecture Owner and Final Approver