feat: implement project bus MVP

docs/ARCHITECTURE.md

@@ -0,0 +1,61 @@
+# Architecture
+
+## Boundary
+
+The Project Bus coordinates formal project events. It does not execute source
+code, clone repositories, inspect artifacts, send chat messages, implement a
+project methodology, or decide what a project should build. Those activities
+remain with authenticated actors and external systems.
+
+## Components
+
+1. `ProjectBusRequestHandler` implements a small stateless MCP Streamable HTTP
+   transport over JSON-RPC 2.0.
+2. `AuthProvider` turns transport credentials into an immutable principal.
+3. `MCPApplication` publishes tools and maps calls to domain operations.
+4. `ProjectBusService` enforces role, lifecycle, independence, idempotency,
+   and gate invariants.
+5. `Database` owns migration and transaction boundaries.
+6. SQLite relational projections support current-state queries; `event_log`
+   is the immutable ordered synchronization source.
+
+## Write path
+
+A mutating call is authenticated before tool dispatch. The service opens
+`BEGIN IMMEDIATE`, resolves the principal to an active project membership,
+checks the idempotency tuple `(project, actor, key)`, validates current state,
+updates the relevant projection, appends exactly one event, stores the
+canonical response, and commits.
+
+The event and projection update therefore succeed or fail together.
+Idempotency replays return the original response without adding an event.
+
+## Event ordering and cursors
+
+SQLite allocates a monotonic integer `cursor` for each event. `sync_since`
+filters by project, returns ascending cursors, and returns the last delivered
+cursor. Consumers persist that value only after processing the response. The
+cursor is global to the database, so gaps within a project's stream are
+normal. Consumers must not infer missing project events from gaps.
+
+This is pull synchronization. The MCP server does not wake a ChatGPT thread or
+push into a dormant CLI session.
+
+## State model
+
+Work packages move through:
+
+`OPEN → CLAIMED → RESULT_SUBMITTED → IN_REVIEW → REVIEWED → ACCEPTED|REJECTED`
+
+`HOLD` leaves a reviewed package in `REVIEWED`. A new review can be requested
+after a completed review. This MVP treats corrections after
+`CHANGES_REQUESTED` as a new work package or a new explicitly governed
+iteration; it does not silently overwrite submitted result evidence.
+
+## Trust boundaries
+
+- Authentication proves an external subject; project membership grants a role.
+- The database is trusted to enforce integrity and append-only triggers.
+- Artifact URIs and commit hashes are references, not trusted content.
+- Reverse proxy identity headers are not consumed by the built-in adapter.
+