feat: initial architecture specification and research

Phase 0→1 setup for alknet-firewall — a behavioral signal detection
library that screens untrusted LLM inputs using small model activations.

Architecture docs (5 specs, 10 ADRs, 7 open questions):
- overview: vision, scope, dependencies, package structure
- firewall: core API, alarm protocol, score composition, error handling
- codebook: SVD basis, spline distributions, calibration, tensor format
- model: activation extraction, model-agnostic interface, lazy loading
- configuration: thresholds, model selection, detection tuning

Research reports:
- modern-python-project-setup: uv, pyproject.toml, src layout, ruff, CI
- python-ml-packaging: optional PyTorch, HF Hub download, safetensors
- llm-input-safety-landscape: threat taxonomy, defenses, academic evidence

Agent role adaptations for Python project (replaced Rust conventions).

.opencode/agents/code-reviewer.md

@@ -96,28 +96,28 @@ Verify:
 - Edge cases considered
 - No brittle tests (over-mocked, timing-dependent)
 
-#### D. Static Analysis (Rust toolchain)
+#### D. Static Analysis (Python toolchain)
 
-Run the project's build, lint, and format commands:
+Run the project's lint, type-check, and format commands:
 
 ```bash
-cargo build                                                   # Build check
-cargo clippy -- -D warnings                                   # Lint
-cargo fmt --check                                              # Format check
+uv run ruff check src/ tests/                                  # Lint
+uv run ruff format --check src/ tests/                         # Format check
+uv run mypy src/                                               # Type check
 ```
 
 #### D2. Project Convention Checks
 
 For this project, also verify:
 
-- No comments in code (per project convention)
-- Error handling uses `anyhow::Result` (application) / `thiserror` (library) — no
-  panics in library code
-- Feature flags are used correctly (`tls`, `iroh`, `acme`) — base crate compiles
-  lean
-- Public API is well-documented with `///` doc comments where appropriate
-- Module structure follows Rust conventions (`mod.rs`, `lib.rs`)
-- No unnecessary `unwrap()` or `expect()` in library code
+- No comments in code (per project convention; docstrings for public API are fine)
+- Error handling uses custom exception classes (subclass `AlknetFirewallError`)
+  for library errors; no silently swallowed exceptions
+- Optional dependencies (torch) use lazy imports with clear error messages
+- Public API is well-documented with docstrings where appropriate
+- Module structure follows Python conventions (`__init__.py` for re-exports)
+- Type hints are present on all public functions
+- Model loading uses safetensors format only (never `.pt`/`.bin` pickle files)
 
 #### E. Security
 

.opencode/agents/coordinator.md

@@ -91,7 +91,7 @@ This is the most critical coordinator responsibility. Follow it exactly:
 
 3. **Validate after every merge:**
    ```bash
-   cargo build && cargo clippy -- -D warnings && cargo test
+   uv sync --locked && uv run ruff check src/ tests/ && uv run mypy src/ && uv run pytest
    ```
    Never skip this. A merge that breaks the build is worse than no merge.
 
@@ -191,7 +191,7 @@ also include:
 Example prompt template:
 
 ```
-You are an implementation specialist for the @alkdev/alknet project.
+You are an implementation specialist for the @alkdev/alknet-firewall project.
 
 Your task: {{task}}
 
@@ -199,18 +199,19 @@ Your task: {{task}}
 2. Read the task file, then read all referenced source files and architecture docs.
 3. Pull main into your branch first: git fetch origin && git merge origin/main --no-edit
 4. Implement the changes, following all acceptance criteria.
-5. Run cargo build, cargo clippy -- -D warnings, cargo test, cargo fmt --check. Fix any failures.
+5. Run uv run ruff check src/ tests/, uv run ruff format --check src/ tests/, uv run mypy src/, uv run pytest. Fix any failures.
 6. Commit ONLY source code — do not commit task files (tasks/*.md). The coordinator manages task status on main.
 7. Push: git push origin $(git branch --show-current)
 8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
 
-Key project constraints (@alkdev/alknet):
-- Rust: use cargo build, cargo clippy, cargo fmt, cargo test
-- No comments in code
-- anyhow::Result for application errors, thiserror for library error types
-- Feature flags for transports (tls, iroh, acme)
-- Async via tokio runtime
-- No panics in library code
+Key project constraints (@alkdev/alknet-firewall):
+- Python: use uv run ruff check, uv run ruff format, uv run mypy, uv run pytest
+- No comments in code (docstrings for public API are fine)
+- Custom exception classes (subclass AlknetFirewallError) for library errors
+- PyTorch is optional dependency via extras — use lazy imports with clear error messages
+- Type hints required on all public functions
+- safetensors format only for model files (never .pt/.bin pickle)
+- Async not required — this is a synchronous inference library
 ```
 
 ### Partial Generation Spawning

.opencode/agents/implementation-specialist.md

@@ -112,17 +112,17 @@ If blocked → Safe Exit (see below)
 ### 4. Self-Verify
 
 ```bash
-# Build
-cargo build
-
 # Lint
-cargo clippy -- -D warnings
-
-# Run tests
-cargo test
+uv run ruff check src/ tests/
 
 # Format check
-cargo fmt --check
+uv run ruff format --check src/ tests/
+
+# Type check
+uv run mypy src/
+
+# Run tests
+uv run pytest
 ```
 
 Check each acceptance criterion in the task file.
@@ -131,7 +131,7 @@ Check each acceptance criterion in the task file.
 
 ```bash
 # Stage only source code — NOT task files
-git add src/ test/ docs/  # or specific files as appropriate
+git add src/ tests/ docs/  # or specific files as appropriate
 git commit -m "feat(<task-id>): <description>"
 git push origin $(git branch --show-current)
 ```
@@ -200,8 +200,8 @@ When available, use memory tools to manage your context:
   assistant messages if you lose track
 - `memory({tool: "search", args: {query: "..."}})` — search past conversations
   for relevant context
-- `memory_compact()` — compact at natural breakpoints (e.g., after completing a
-  subtask) when context is above 80%
+- `memory_compact()` — compact at natural breakpoints (e.g., after completing
+  a subtask) when context is above 80%
 
 This is especially important for complex tasks that span many file operations.
 
@@ -209,16 +209,23 @@ This is especially important for complex tasks that span many file operations.
 
 Read `AGENTS.md` at project root for full details. Key rules:
 
-1. **No comments in code** — Per project convention.
-2. **Error handling** — Use `anyhow::Result` for application code, `thiserror` for
-   library error types. Never panic in library code.
-3. **Feature flags** — Transports are feature-gated (`tls`, `iroh`, `acme`). Base
-   crate should compile lean.
-4. **Async runtime** — `tokio` is the async runtime. All I/O is async.
-5. **Naming conventions** — Rust standard: `snake_case` for functions/variables/
-   modules, `PascalCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
-6. **Module structure** — One module per component under `src/`. Re-export via
-   `mod.rs` or `lib.rs` as appropriate.
+1. **Type hints required** — All public functions must have type annotations.
+   Use `mypy --strict` for validation.
+2. **Error handling** — Use custom exception classes for library errors
+   (subclass from `AlknetFirewallError`). Use explicit `Result` patterns or
+   raised exceptions; never silently swallow errors.
+3. **Optional dependencies** — PyTorch is an optional dependency via extras.
+   Use lazy imports with clear error messages when torch is not installed.
+4. **Naming conventions** — Python standard: `snake_case` for functions/variables/
+   modules, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
+5. **Module structure** — One module per component under `src/alknet_firewall/`.
+   Use `__init__.py` for public API re-exports.
+6. **Testing** — Unit tests in `tests/`, integration tests marked with
+   `@pytest.mark.integration`. Mock ML model loading in unit tests; use tiny
+   models for integration tests.
+7. **No comments in code** — Per project convention. Use docstrings for public API.
+8. **safetensors only** — Never load pickle-based `.pt`/`.bin` model files.
+   Always use safetensors format for security.
 
 ## Key Principles