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).
This commit is contained in:
2026-06-13 05:17:40 +00:00
parent 141628bae4
commit cf464c2296
23 changed files with 3900 additions and 44 deletions

View File

@@ -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