docs: describe the write-ahead audit model and bring the contract files up to date

CLAUDE.md

@@ -12,12 +12,9 @@ HTTP, using the official `mcp` SDK v2 low-level `Server`. Full access by default
 and the Gitea token scope. Auth modes: admin-token (`GITEA_TOKEN` / static
 `MCP_BEARER_TOKEN`) and per-user OAuth on HTTP (user's own Gitea token).
 
-The project is mid-rebuild (chunk plan in `docs/audit.md`). Built so far: tooling,
-`config.py`, `identity.py`, `errors.py`, the generated catalog (`catalog/`), the
-Gitea executor (`gitea/`), the setup command (`setup_cmd.py`, `setup_snippets.py`,
-`setup_template.py`), the integration harness, CI and audit/security/limits
-helpers. Planned: server and transports (B4), OAuth (B5), smoke tests (B9),
-docs (B11).
+The rebuild is complete: catalog, executor, server, both transports, per-user OAuth,
+setup command, CI, security suite, MCP smoke tests and the live integration suite are in.
+The remaining open items are tracked in `docs/roadmap.md`.
 
 ## Commands
 
@@ -27,7 +24,7 @@ make lint               # ruff check, ruff format --check, mypy src
 make format             # ruff format + ruff check --fix
 make test               # uv run pytest (coverage gate)
 make test-integration   # AEGIS_INTEGRATION=1, needs Docker
-make run                # uv run aegis-gitea-mcp serve (not implemented until B4)
+make run                # uv run aegis-gitea-mcp serve
 uv run python scripts/generate_catalog.py --check   # catalog matches the spec
 make validate-audit     # verify audit hash chain
 uv run pytest tests/test_config.py::test_defaults -v   # single test
@@ -44,11 +41,12 @@ uv run pytest tests/test_config.py::test_defaults -v   # single test
   upload building, `SLASH_ROUTES`), `pagination.py`, `redaction.py`.
 - `setup_cmd.py`, `setup_snippets.py`, `setup_template.py` (done): the `setup`
   command, its client snippets and the built-in `.env` template.
-- Server (B4, planned): low-level SDK `Server` with one `on_list_tools` and one
+- `server.py` (done): low-level SDK `Server` with one `on_list_tools` and one
   `on_call_tool` dispatcher, jsonschema validation, audit, `is_error` results for
-  tool failures, `gitea_api_request` escape-hatch tool.
-- Auth (B5, planned): static bearer verifier and OAuth provider with encrypted
-  token store.
+  tool failures, `gitea_api_request` escape-hatch tool. `transports.py`: stdio
+  runner and streamable HTTP app.
+- `auth.py` and `oauth/` (done): static bearer verifier and the OAuth provider
+  with encrypted token store.
 - Core helpers (done): `config.py` (`Settings`, `get_settings()`,
   `reset_settings()`), `identity.py`, `errors.py` (`ToolError`,
   `GiteaAPIError`), `audit.py`, `security.py`, `response_limits.py`,
@@ -61,7 +59,9 @@ points `DATA_DIR`/`AUDIT_LOG_PATH` into `tmp_path`.
 
 ## Invariants
 
-Kept: audit event per tool call; no secrets in logs/errors/results; no stack
+Kept: write-ahead audit (a `tool_call_started` entry before the call runs, the
+call is refused when it cannot be written, a `tool_invocation` entry with the
+outcome after it; count calls by `tool_invocation`); no secrets in logs/errors/results; no stack
 traces by default; `127.0.0.1` default bind and fail-closed HTTP auth off
 loopback; untrusted-content labelling; schema validation with no extra
 properties; response size bounds; validated `GITEA_URL` and strict
@@ -73,7 +73,7 @@ Details in `AGENTS.md`.
 
 Python 3.10+, line length 100, ruff (E,W,F,I,B,C4,UP,S,SIM,RUF) plus ruff format,
 strict-ish mypy (`disallow_untyped_defs`, relaxed in tests). Public functions need
-docstrings and type hints. Coverage 80% now, 90% from the final chunk. All
+docstrings and type hints. Coverage gate 90%. All
 documentation goes under `docs/`; security-impacting changes update docs in the
 same changeset. No em-dashes in text.