feat: WP-0001 foundation + WP-0002 core extensions

WP-0001 — Foundation & GAAF Baseline
- SCOPE.md, ARCHITECTURE-LAYERS.md, contracts/ tree
- .claude/rules/ stubs filled (architecture, stack, boundary)
- 57 tests (pytest), pyproject.toml with ruff+mypy, CI workflow

WP-0002 — Core Extensions (FR-4 + FR-3)
- FR-4: BudgetTracker (thread-safe) + LLMBudgetExceededError +
  optional RunConfig.budget_tracker + enforcement in all adapters
- FR-3: async_execute_prompt on LLMAdapter ABC (asyncio.to_thread
  fallback) + native asyncio.create_subprocess_exec in ClaudeCodeAdapter

81 tests passing.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ARCHITECTURE-LAYERS.md

@@ -0,0 +1,94 @@
+# ARCHITECTURE-LAYERS.md
+
+**Framework:** GAAF-2026  
+**Last reviewed:** 2026-04-01  
+**Repository purpose:** Multi-provider LLM client library — unified adapter interface for Python  
+**Next review:** 2026-07-01
+
+---
+
+## Layer Map
+
+### Core (high rigidity — frozen after v1)
+
+Domain-agnostic primitives. Must not change without a major version bump once stable.
+
+| Module | Contents |
+|--------|----------|
+| `adapter.py` | `LLMAdapter` ABC (`execute_prompt`, `validate_config`); `MockLLMAdapter`; `ErrorLLMAdapter` |
+| `models.py` | `RunConfig`, `LLMResponse` dataclasses |
+| `exceptions.py` | `LLMError` → `LLMConfigurationError`, `LLMAPIError`, `LLMRateLimitError`, `LLMTimeoutError`, `LLMSubprocessError` |
+
+**Contract:** `contracts/core/llm-adapter.md`
+
+### Functional (medium rigidity — evolvable, versioned)
+
+Value-realization modules. Each adapter is independently shippable.
+Maturity states: **Experimental → Beta → Stable → Deprecated**
+
+| Module | Contents | Maturity |
+|--------|----------|----------|
+| `openai.py` | `OpenAIAdapter` — OpenAI chat completions | Beta |
+| `gemini.py` | `GeminiAdapter` — Google Generative Language API | Beta |
+| `openrouter.py` | `OpenRouterAdapter` — OpenAI-compatible multi-model routing | Beta |
+| `claude_code.py` | `ClaudeCodeAdapter` — `claude --print` subprocess | Beta |
+| `embedding_adapter.py` | `EmbeddingAdapter` ABC | Beta |
+| `embedding_openai.py` | `OpenAICompatibleEmbeddingAdapter` | Beta |
+| `embedding_cache.py` | `EmbeddingCache` — disk-backed embedding cache | Beta |
+| `embedding_factory.py` | `create_embedding_adapter()` factory | Beta |
+| `factory.py` | `create_adapter()` factory — lazy provider registration | Beta |
+| `_token_estimator.py` | Rough token count estimation (word-based) | Beta |
+| `similarity.py` | `cosine_similarity`, `similarity_matrix`, `find_similar_pairs` | Beta |
+
+**Planned additions (WP-0003):** `RoutingPolicy`, `server.py`  
+**Contracts:** `contracts/functional/`
+
+### Configuration (very low rigidity — user-controlled declarative state)
+
+| Module | Contents |
+|--------|----------|
+| `toml_config.py` | `resolve_llm()` — 7-level TOML priority chain; `ResolvedLLM`; `LLMLayer` |
+| `config.py` | `LLMConfig` dataclass; `resolve_api_key()`; `find_project_root()`; `load_config()` |
+| `_http.py` | Shared HTTP POST utility (used by Functional adapters) |
+
+**Contracts:** `contracts/config/`
+
+---
+
+## Dependency Rule
+
+```
+Core  ←  Functional  ←  Configuration
+```
+
+Upward dependencies (Configuration → Functional, Functional → Core) are **prohibited**.  
+`_http.py` sits in the Configuration layer but is consumed only by Functional adapters — acceptable as a shared utility with no upward reach.
+
+---
+
+## Decisions Log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2026-04-01 | FR-3 async: default executor fallback on ABC rather than abstract method | Non-breaking; existing adapters remain valid; native async opt-in per adapter |
+| 2026-04-01 | FR-4 BudgetTracker: optional field on RunConfig, not a separate context object | Keeps RunConfig as single call config; avoids thread-local / contextvar complexity |
+| 2026-04-01 | FR-1 HTTP server: optional dep `[server]`, not runtime dep | Keeps base install lightweight; most consumers call the library directly |
+
+---
+
+## GAAF-2026 Scorecard (initial baseline — 2026-04-01)
+
+> Scoring: 0 = absent / harmful · 5 = excellent
+
+| Dimension | Score | Notes |
+|-----------|-------|-------|
+| **Core** | 2.5 | ABC and models well-defined; no formal contracts, no tests, no invariant docs yet |
+| **Functional** | 2.5 | Adapters isolated and independently usable; no maturity labels enforced, no tests |
+| **Customization** | n/a | Not applicable (library, not SaaS) |
+| **Configuration** | 2.0 | TOML chain works; no schema validation; `markitect` name coupling in toml_config defaults |
+| **Extensions** | n/a | Not applicable yet (RoutingPolicy + server in WP-0003) |
+| **Cross-layer** | 2.0 | Dependency direction correct; no CI fitness functions; no import graph checks |
+| **Weighted total** | ~2.3 | Usable but vulnerable — WP-0001 targets ≥ 3.5 |
+
+**Target after WP-0001:** ≥ 3.5 (Strong)  
+**Target after WP-0002 + WP-0003:** ≥ 4.0 (Strong / Exemplary)