rewrite phase 1

README.md

@@ -4,6 +4,23 @@ Agent CI is a private Gitea webhook host that turns issue and pull-request comme
 OpenCode planning and implementation workflows. Docker Compose runs the webhook worker and a
 private OpenCode server on the same Docker network as Gitea.
 
+## Architecture
+
+The service has one durable execution path:
+
+```text
+webhook -> repository -> reducer -> durable task -> worker -> workflow -> integration
+```
+
+`engine/reducer.py` is the pure job state machine. `engine/repository.py` applies its transitions
+atomically to SQLite and persists the resulting tasks. `worker.py` executes those tasks and passes
+an explicit `JobRun` into the functions under `workflows/`. The top-level Gitea, Git, OpenCode,
+development, and CodeGraph modules own external effects.
+
+Jobs and workflows are immutable snapshots. Workflows return their final comment body directly;
+progress and resource links are emitted as state-machine events through `JobRun`. The `jobs` table
+is the authoritative state snapshot, while `job_events` provides durable idempotency and audit data.
+
 ## Commands
 
 | Location | Command | Behavior |
@@ -153,9 +170,12 @@ uv sync
 uv run ruff check .
 uv run pyright
 uv run pytest
+uv run pytest --cov=agentci --cov-branch
 docker compose config
 docker compose build
 ```
 
-The tests fail if any tracked Python file exceeds 250 lines. Prompts and JSON schemas live outside
-Python so orchestration modules remain small and readable.
+The coverage command is an opt-in diagnostic report; the regular test run remains the default and
+coverage percentage is not used as a pass threshold.
+
+Prompts and JSON schemas live outside Python so orchestration remains focused on execution flow.