docs: add TEST-NEEDS.md and/or PROOF-NEEDS.md from audit

Documents testing and proof gaps identified during batch audit.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

PROOF-NEEDS.md

@@ -0,0 +1,25 @@
+# PROOF-NEEDS.md — php-aegis
+
+## Current State
+
+- **src/abi/*.idr**: NO
+- **Dangerous patterns**: 0
+- **LOC**: ~10,200 (PHP)
+- **ABI layer**: Missing
+
+## What Needs Proving
+
+| Component | What | Why |
+|-----------|------|-----|
+| Security header generation | Generated headers are well-formed and complete | Malformed security headers leave sites unprotected |
+| CSP policy construction | Content Security Policy prevents all XSS vectors | Incomplete CSP allows cross-site scripting |
+| Webmention validation | IndieWeb Webmention verification is correct | Spoofed webmentions inject malicious content |
+| Input validation | All validators reject malicious input | Validator bypass is a security vulnerability |
+
+## Recommended Prover
+
+**Idris2** — Create `src/abi/` with security header correctness types. CSP policy completeness is a natural fit for exhaustive pattern matching. PHP code would need a separate verification approach (potentially PHPStan + custom rules).
+
+## Priority
+
+**MEDIUM** — Security library deployed on production websites (lcb-website uses it). Incorrect security headers directly expose users to attacks. CSP completeness is the highest-value proof target.

TEST-NEEDS.md

@@ -0,0 +1,59 @@
+# TEST-NEEDS.md — php-aegis
+
+> Generated 2026-03-29 by punishing audit.
+
+## Current State
+
+| Category     | Count | Notes |
+|-------------|-------|-------|
+| Unit tests   | 11    | HeadersTest, SanitizerTest, TurtleEscaperTest, ValidatorTest, WordPress/AdapterTest, IndieWeb/(MicropubTest, IndieAuthTest, WebmentionTest), RateLimit/(TokenBucketTest, StoreTest, RateLimiterTest) |
+| Integration  | 3     | validation/RealWorldTest.php, run-tests.php, test-cf7-xss.php |
+| E2E          | 0     | None |
+| Benchmarks   | 0     | None |
+
+**Source modules:** 14 PHP source files in src/. Covers: headers, sanitizer, turtle escaper, validator, WordPress adapter, IndieWeb (Micropub, IndieAuth, Webmention), RateLimit (TokenBucket, Store, RateLimiter).
+
+## What's Missing
+
+### P2P (Property-Based) Tests
+- [ ] Sanitizer: property tests with arbitrary HTML/JS input
+- [ ] Validator: property tests for all input types
+- [ ] Rate limiter: property tests for token bucket invariants (never negative, refill correctness)
+- [ ] Headers: property tests for CSP generation correctness
+
+### E2E Tests
+- [ ] Full request lifecycle: incoming request -> sanitize -> validate -> rate check -> process -> headers
+- [ ] WordPress integration: full plugin activation -> request -> response with security headers
+- [ ] IndieWeb: full Micropub/IndieAuth/Webmention flow with validation
+
+### Aspect Tests
+- **Security:** XSS test exists (test-cf7-xss.php, good). Missing: SQL injection, CSRF bypass, header injection, rate limiter bypass, authentication timing attacks — a security library needs exhaustive security tests
+- **Performance:** No request processing overhead benchmarks
+- **Concurrency:** No tests for rate limiter under concurrent requests
+- **Error handling:** No tests for malformed headers, invalid token formats, WordPress incompatibility
+
+### Build & Execution
+- [ ] PHPUnit runner setup
+- [ ] Composer autoload verification
+- [ ] WordPress test environment
+
+### Benchmarks Needed
+- [ ] Header generation overhead per request
+- [ ] Sanitizer throughput per input size
+- [ ] Rate limiter decision time
+- [ ] Validator throughput
+
+### Self-Tests
+- [ ] Security header compliance verification
+- [ ] Rate limiter self-test under load
+- [ ] Validator coverage report (all input types tested)
+
+## Priority
+
+**HIGH.** 14 source files with 11 test files is actually a good ratio (79%). But this is a SECURITY library — the test depth needs to be extreme, not just file-count-adequate. The XSS real-world test is commendable. Missing: fuzzing, property tests for all security functions, concurrency tests for the rate limiter. No benchmarks means you cannot prove the security overhead is acceptable.
+
+## FAKE-FUZZ ALERT
+
+- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing
+- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file
+- Priority: P2 — creates false impression of fuzz coverage