docs: add reference checklists for testing, security, performance

z23cc · z23cc · commit 4e62c55133fa · 2026-04-07T05:15:40.000+08:00
- testing-patterns.md: AAA pattern, mock boundaries, Rust test patterns, anti-patterns, prove-it workflow
- security-checklist.md: OWASP Top 10, secret scanning, cargo audit, SQL safety, input validation
- performance-checklist.md: cargo bench/flamegraph, DB anti-patterns, async/await patterns, tokio runtime

Task: fn-136-borrow-agent-skills-patterns-anti.2
diff --git a/docs/references/performance-checklist.md b/docs/references/performance-checklist.md
@@ -0,0 +1,152 @@
+# Performance Checklist
+
+Quick reference for performance in flow-code. Rust backend with libSQL, async runtime.
+
+## Measurement Commands
+
+```bash
+# Rust benchmarks (add benches/ directory with criterion)
+cargo bench
+
+# Criterion (statistical benchmarking)
+cargo bench --bench my_benchmark
+
+# Flamegraph (CPU profiling)
+cargo install flamegraph
+cargo flamegraph --bin flowctl -- status --json
+
+# Memory profiling (Linux)
+valgrind --tool=massif target/release/flowctl status --json
+
+# Binary size
+ls -lh target/release/flowctl
+cargo bloat --release --crates
+
+# Compile time
+cargo build --release --timings
+```
+
+| Tool | What It Measures | When to Use |
+|---|---|---|
+| `cargo bench` (criterion) | Function-level latency | Before/after optimization |
+| `cargo flamegraph` | CPU hotspots | Investigating slow commands |
+| `cargo bloat` | Binary size by crate | When binary grows unexpectedly |
+| `valgrind --tool=massif` | Heap allocations | Investigating memory usage |
+| `hyperfine` | CLI command latency | Comparing command performance |
+
+## Database Anti-Patterns (libSQL)
+
+| Anti-Pattern | Impact | Fix |
+|---|---|---|
+| N+1 queries | Linear DB round-trips | Use JOINs or batch queries |
+| Unbounded queries | Memory exhaustion, timeouts | Always use LIMIT, paginate |
+| Missing indexes | Slow reads as data grows | Add indexes on filtered/sorted columns |
+| No connection pooling | Connection overhead per query | Reuse connections |
+| SELECT * | Fetches unused columns | Select only needed columns |
+| String concatenation in SQL | Injection risk + no query cache | Use parameterized queries |
+| No transactions for batch ops | Partial failures, inconsistency | Wrap in BEGIN/COMMIT |
+
+## Backend CLI Checklist
+
+| Area | Target | How to Verify |
+|---|---|---|
+| Command startup | < 50ms | `hyperfine 'flowctl status --json'` |
+| Task list (100 tasks) | < 200ms | Benchmark with test data |
+| Database open | < 20ms | Profile with `tracing` spans |
+| JSON serialization | < 5ms for typical output | `cargo bench` |
+| Binary size | < 20MB release | `ls -lh target/release/flowctl` |
+| Memory usage (idle) | < 10MB | `valgrind` or `/usr/bin/time -v` |
+
+## Rust-Specific Performance
+
+### Async/Await Patterns
+
+| Do | Don't |
+|---|---|
+| Use `tokio::spawn` for concurrent I/O | Block the async runtime with sync I/O |
+| Use `tokio::task::spawn_blocking` for CPU work | Run CPU-heavy code in async context |
+| Use `tokio::join!` for parallel awaits | Await sequentially when independent |
+| Use bounded channels for backpressure | Use unbounded channels (memory leak risk) |
+
+```rust
+// Good: parallel async operations
+let (tasks, epics) = tokio::join!(
+    db.list_tasks(),
+    db.list_epics()
+);
+
+// Bad: sequential when independent
+let tasks = db.list_tasks().await?;
+let epics = db.list_epics().await?;  // Waits unnecessarily
+```
+
+### Memory Patterns
+
+| Do | Don't |
+|---|---|
+| Use `&str` over `String` where possible | Clone strings unnecessarily |
+| Use `Cow<str>` for maybe-owned data | Allocate when borrowing suffices |
+| Pre-allocate with `Vec::with_capacity` | Push to vec without size hint |
+| Use iterators over collecting into vecs | `collect()` when you can chain |
+| Use `Arc` for shared read-only data | Clone large structs across threads |
+
+```rust
+// Good: pre-allocate
+let mut results = Vec::with_capacity(tasks.len());
+
+// Bad: repeated reallocation
+let mut results = Vec::new();  // Grows 1, 2, 4, 8...
+```
+
+### String Performance
+
+| Do | Don't |
+|---|---|
+| Use `write!` or `format!` once | Repeated `push_str` / `+` concatenation |
+| Use `String::with_capacity` for building | Build strings without size hint |
+| Return `impl Display` for lazy formatting | Format eagerly when output may not be used |
+| Use `serde_json::to_writer` for streaming | Serialize to String then write |
+
+## Tokio Runtime
+
+| Setting | Recommendation |
+|---|---|
+| Runtime flavor | `current_thread` for CLI (lower overhead) |
+| Worker threads | Default for server, 1 for CLI tools |
+| Blocking threads | Default (512), reduce for CLI |
+| Task budget | Let tokio manage; avoid manual yielding |
+
+```rust
+// CLI tool: single-threaded runtime (faster startup)
+#[tokio::main(flavor = "current_thread")]
+async fn main() { ... }
+
+// Server: multi-threaded (default)
+#[tokio::main]
+async fn main() { ... }
+```
+
+## Performance Anti-Patterns
+
+| Anti-Pattern | Impact | Fix |
+|---|---|---|
+| Blocking async runtime | Starves other tasks | Use `spawn_blocking` |
+| N+1 database queries | Linear latency growth | Batch or JOIN queries |
+| Cloning large structs | Memory + CPU waste | Use references or `Arc` |
+| Unbounded collections | Memory exhaustion | Add limits, use streaming |
+| Sync file I/O in async | Blocks executor thread | Use `tokio::fs` |
+| Excessive logging in hot path | I/O overhead | Use log levels, sample |
+| Compiling in debug mode for perf tests | 10-100x slower | Always `--release` |
+| Not reusing DB connections | Connection overhead | Use connection pool |
+| Serializing then parsing JSON | Double work | Pass typed structs |
+| Formatting strings nobody reads | CPU waste | Lazy formatting with `Display` |
+
+## Profiling Workflow
+
+| Step | Command | Purpose |
+|---|---|---|
+| 1. Baseline | `hyperfine 'flowctl status --json'` | Measure current perf |
+| 2. Profile | `cargo flamegraph --bin flowctl -- status` | Find hotspots |
+| 3. Optimize | Edit code targeting hotspot | Reduce cost |
+| 4. Verify | Re-run baseline command | Confirm improvement |
+| 5. Benchmark | `cargo bench` | Prevent regression |
diff --git a/docs/references/security-checklist.md b/docs/references/security-checklist.md
@@ -0,0 +1,141 @@
+# Security Checklist
+
+Quick reference for security in flow-code. CLI tool handling local state, no web server.
+
+## Pre-Commit Secret Scan
+
+```bash
+# Check staged files for secrets before committing
+git diff --cached | grep -iE \
+  "password\s*=|secret\s*=|api_key\s*=|token\s*=|private_key|BEGIN RSA|BEGIN EC"
+
+# Patterns to catch
+grep -rn "AKIA[0-9A-Z]{16}"              # AWS access keys
+grep -rn "sk-[a-zA-Z0-9]{48}"            # OpenAI API keys
+grep -rn "ghp_[a-zA-Z0-9]{36}"           # GitHub personal tokens
+grep -rn "xoxb-[0-9]{10,}"               # Slack bot tokens
+```
+
+## Files to Never Commit
+
+| File/Pattern | Reason | Mitigation |
+|---|---|---|
+| `.env` | Contains secrets | Add to `.gitignore` |
+| `*.pem`, `*.key` | Private keys | Add to `.gitignore` |
+| `.flow/` | Runtime state (may contain tokens) | Add to `.gitignore` |
+| `credentials.json` | Service account keys | Add to `.gitignore` |
+| `*.upstream` | Backup files with potential secrets | Add to `.gitignore` |
+
+Commit `.env.example` with placeholder values instead of `.env`.
+
+## Secrets Management
+
+| Do | Don't |
+|---|---|
+| Use environment variables for secrets | Hardcode secrets in source |
+| Commit `.env.example` with placeholders | Commit `.env` with real values |
+| Use `--json` flag for machine parsing | Parse human-readable output with secrets |
+| Rotate secrets after exposure | Ignore leaked credentials |
+| Scope API keys to minimum permissions | Use admin keys for all operations |
+
+## OWASP Top 10 Quick Reference
+
+| # | Vulnerability | Prevention |
+|---|---|---|
+| 1 | Broken Access Control | Auth checks on every endpoint, ownership verification |
+| 2 | Cryptographic Failures | HTTPS, strong hashing, no secrets in code |
+| 3 | Injection | Parameterized queries, input validation |
+| 4 | Insecure Design | Threat modeling, spec-driven development |
+| 5 | Security Misconfiguration | Minimal permissions, audit deps, secure defaults |
+| 6 | Vulnerable Components | `cargo audit`, `cargo deny`, minimal deps |
+| 7 | Auth Failures | Strong passwords, rate limiting, session management |
+| 8 | Data Integrity Failures | Verify updates/dependencies, signed artifacts |
+| 9 | Logging Failures | Log security events, don't log secrets |
+| 10 | SSRF | Validate/allowlist URLs, restrict outbound requests |
+
+## Dependency Audit (Rust)
+
+```bash
+# Audit for known vulnerabilities
+cargo audit
+
+# Deny specific licenses or advisories
+cargo deny check
+
+# Check for outdated dependencies
+cargo outdated
+
+# Minimal dependency tree (fewer deps = smaller attack surface)
+cargo tree | wc -l
+```
+
+| Tool | Purpose | When to Run |
+|---|---|---|
+| `cargo audit` | CVE database check | Pre-commit, CI |
+| `cargo deny` | License + advisory policy | CI pipeline |
+| `cargo outdated` | Stale dependency check | Weekly/monthly |
+| `cargo tree` | Dependency graph audit | When adding deps |
+
+## Input Validation
+
+| Rule | Example |
+|---|---|
+| Validate at boundaries only | CLI args, JSON input, file reads |
+| Use allowlists, not denylists | Accept known-good, reject everything else |
+| Constrain string lengths | Task titles: 1-500 chars |
+| Validate file paths | No `..` traversal, stay within `.flow/` |
+| Sanitize output for shells | Escape special chars in generated commands |
+| Parse, don't validate | Deserialize into typed structs, not raw strings |
+
+```rust
+// Good: parse into typed struct at boundary
+let task: TaskInput = serde_json::from_str(&input)?;
+
+// Bad: pass raw string around and validate later
+fn process(raw: &str) { /* who validates this? */ }
+```
+
+## Error Handling
+
+| Context | Approach |
+|---|---|
+| CLI output (user-facing) | Clear error message, no stack traces |
+| JSON output (`--json`) | Structured error: `{"error": "message"}` |
+| Internal logging | Full context, file/line, but no secrets |
+| Panics | Catch at boundaries with `catch_unwind` or `?` |
+
+```rust
+// Good: generic error to user, detail in logs
+eprintln!("Error: failed to open database");
+tracing::error!("DB open failed: {:?} at {:?}", err, path);
+
+// Bad: expose internals
+eprintln!("Error: {}", err);  // May leak path, SQL, etc.
+```
+
+## SQL Safety (libSQL)
+
+| Do | Don't |
+|---|---|
+| Use parameterized queries | Concatenate user input into SQL |
+| Use `?` placeholders | Use `format!()` for query building |
+| Validate types before query | Trust raw input as safe |
+| Use transactions for multi-step ops | Execute multiple queries without atomicity |
+
+```rust
+// Good: parameterized
+conn.execute("INSERT INTO tasks (title) VALUES (?1)", [&title]).await?;
+
+// Bad: string concatenation
+conn.execute(&format!("INSERT INTO tasks (title) VALUES ('{}')", title), ()).await?;
+```
+
+## File System Security
+
+| Rule | Rationale |
+|---|---|
+| Validate paths stay within `.flow/` | Prevent directory traversal |
+| Use temp dirs for scratch work | Don't pollute user directories |
+| Set restrictive permissions on state files | Protect `.flow/` data |
+| Clean up temp files on exit | No stale sensitive data |
+| Don't follow symlinks blindly | Potential symlink attacks |
diff --git a/docs/references/testing-patterns.md b/docs/references/testing-patterns.md
