first pass at the newspaper builder

.aidlc/knowledge/aidlc-devsecops-agent/nfr-requirements-guide.md

@@ -0,0 +1,188 @@
+# NFR Requirements Guide
+
+## Performance Requirement Benchmarking
+
+### How to Define Performance Requirements
+Every performance requirement must specify:
+- **Metric**: What is being measured (response time, throughput, resource usage)
+- **Target**: The quantitative threshold
+- **Percentile**: Which percentile the target applies to (p50, p95, p99)
+- **Load condition**: Under what concurrency/traffic the target must hold
+- **Measurement method**: How and where the metric is captured
+
+### Common Performance Targets by Application Type
+
+| Application Type | Metric | Target | Percentile | Notes |
+|-----------------|--------|--------|------------|-------|
+| Web application (interactive) | Page load time | < 2s | p95 | First contentful paint |
+| REST API (synchronous) | Response time | < 200ms | p99 | Excludes network transit |
+| Search query | Result delivery | < 500ms | p95 | Including ranking |
+| Batch processing | Throughput | N records/min | Average | Define minimum acceptable rate |
+| Real-time messaging | End-to-end latency | < 100ms | p99 | From send to delivery |
+| File upload | Processing time | < 5s per MB | p95 | Post-upload processing |
+
+### Performance Anti-Requirements
+Explicitly exclude unreasonable expectations:
+- "The system should be fast" (not measurable)
+- "All pages load instantly" (no target, no percentile)
+- "Handle unlimited users" (no capacity boundary)
+
+Replace with: "The dashboard page loads in < 3 seconds at p95 under 500 concurrent users."
+
+## Scalability Assessment Frameworks
+
+### Capacity Planning Template
+
+| Dimension | Current | 6-Month Target | 12-Month Target | Scaling Mechanism |
+|-----------|---------|---------------|-----------------|-------------------|
+| Concurrent users | N | N * X | N * Y | Horizontal auto-scaling |
+| Data volume | N GB | N * X GB | N * Y GB | Partitioning strategy |
+| Requests per second | N | N * X | N * Y | Load balancer + replicas |
+| Storage growth rate | N GB/month | N * X GB/month | N * Y GB/month | Tiered storage policy |
+
+### Scalability Requirement Format
+```
+NFR-SCALE-NNN: [Scalability Requirement]
+Current baseline: [measured current capacity]
+Target capacity: [required capacity at specific timeline]
+Growth model: [linear, exponential, seasonal, step-function]
+Scaling approach: [horizontal, vertical, partitioning, caching]
+Cost constraint: [infrastructure cost must remain below $X/month at target scale]
+Degradation policy: [what degrades first when approaching capacity limits]
+```
+
+### Scaling Decision Matrix
+
+| Signal | Scale Up | Scale Out | Optimize First |
+|--------|----------|-----------|----------------|
+| CPU consistently > 70% | Single-instance workloads | Stateless services | Check for inefficient algorithms |
+| Memory pressure | In-memory processing | Distributed cache | Check for memory leaks |
+| I/O wait > 30% | Faster storage tier | Read replicas, sharding | Query optimization, indexing |
+| Queue depth growing | Faster consumers | More consumer instances | Batch size tuning |
+| Connection pool exhausted | Larger pool size | Connection multiplexing | Connection leak investigation |
+
+## Reliability Target-Setting
+
+### SLA/SLO/SLI Hierarchy
+
+| Term | Definition | Example | Who Defines |
+|------|-----------|---------|-------------|
+| **SLI** (Indicator) | The metric being measured | Successful requests / total requests | Engineering |
+| **SLO** (Objective) | Internal target for the SLI | 99.95% success rate over 30 days | Engineering + Product |
+| **SLA** (Agreement) | External contractual commitment | 99.9% uptime with financial penalties | Business + Legal |
+
+**Rule**: SLO must be stricter than SLA. If SLA is 99.9%, set SLO at 99.95% to provide an internal buffer.
+
+### Availability Targets and Their Implications
+
+| Availability | Downtime / Year | Downtime / Month | Requires |
+|-------------|-----------------|-------------------|----------|
+| 99% (two nines) | 3.65 days | 7.3 hours | Basic monitoring, manual recovery |
+| 99.9% (three nines) | 8.76 hours | 43.8 minutes | Auto-restart, health checks, alerting |
+| 99.95% | 4.38 hours | 21.9 minutes | Multi-AZ, automated failover, load balancing |
+| 99.99% (four nines) | 52.6 minutes | 4.38 minutes | Multi-region active-active, zero-downtime deploys |
+| 99.999% (five nines) | 5.26 minutes | 26.3 seconds | Fully automated everything, extensive redundancy |
+
+### Recovery Objectives
+
+| Objective | Definition | How to Set |
+|-----------|-----------|------------|
+| **RTO** (Recovery Time Objective) | Maximum acceptable time to restore service | Based on business impact per hour of downtime |
+| **RPO** (Recovery Point Objective) | Maximum acceptable data loss window | Based on cost of recreating or losing data |
+| **MTTR** (Mean Time to Recovery) | Average time to restore from failure | Measured operationally; target should be < RTO |
+| **MTBF** (Mean Time Between Failures) | Average time between failures | Measured operationally; drives reliability investment |
+
+## Observability Requirements
+
+### Three Pillars Specification
+
+#### Metrics Requirements
+Define for each component:
+- **Business metrics**: Conversion rate, revenue processed, active users
+- **Application metrics**: Request rate, error rate, latency (RED method)
+- **Infrastructure metrics**: CPU, memory, disk, network (USE method)
+- **Retention**: How long to keep each metric tier (1 min granularity for 7 days, 5 min for 30 days, 1 hour for 1 year)
+
+#### Logging Requirements
+| Log Level | When to Use | Retention | Indexing |
+|-----------|------------|-----------|---------|
+| ERROR | Unrecoverable failures requiring attention | 90 days | Full-text indexed |
+| WARN | Recoverable issues, degraded behavior | 30 days | Full-text indexed |
+| INFO | Significant business events, state transitions | 30 days | Structured fields only |
+| DEBUG | Diagnostic detail for troubleshooting | 7 days | Not indexed (stored only) |
+
+#### Tracing Requirements
+- Distributed traces across all service boundaries
+- Trace context propagation via W3C Trace Context headers
+- Sampling strategy: 100% for errors, 10% for normal traffic (adjust for volume)
+- Trace retention: 7 days at full detail, 30 days for trace metadata
+
+### Alerting Requirements Template
+For each alert:
+```
+Alert: [descriptive name]
+SLI: [which service level indicator]
+Threshold: [when to fire -- e.g., error rate > 1% for 5 minutes]
+Severity: [page (wake someone up) | ticket (next business day) | log (informational)]
+Runbook: [link to response procedure]
+Notification: [who gets notified via which channel]
+Auto-remediation: [if any automated response is triggered]
+```
+
+### Observability Anti-Patterns to Avoid
+- Alerting on causes instead of symptoms (alert on error rate, not CPU usage)
+- Missing correlation IDs across service boundaries
+- Logging sensitive data (PII, credentials, tokens)
+- Alert fatigue from noisy thresholds (tune before deploying)
+- Dashboard sprawl without clear ownership (every dashboard needs an owner)
+
+## Security Requirement Templates
+
+### Authentication Requirements
+```
+NFR-AUTH-NNN: [Authentication Requirement]
+Method: [OAuth 2.0, JWT, session-based, API key, mTLS]
+Token lifetime: [access token TTL, refresh token TTL]
+MFA requirement: [none, optional, required for admin, required for all]
+Session management: [max concurrent sessions, idle timeout, absolute timeout]
+Password policy: [min length, complexity, rotation, breach detection]
+```
+
+### Authorization Requirements
+```
+NFR-AUTHZ-NNN: [Authorization Requirement]
+Model: [RBAC, ABAC, ACL, policy-based]
+Roles: [list of roles and their permission boundaries]
+Resource granularity: [organization, team, user, resource-level]
+Delegation: [can users delegate permissions, under what constraints]
+Audit: [which authorization decisions are logged]
+```
+
+### Data Protection Requirements
+```
+NFR-DATA-NNN: [Data Protection Requirement]
+Classification: [public, internal, confidential, restricted]
+Encryption at rest: [algorithm, key management, rotation schedule]
+Encryption in transit: [TLS version, cipher suites, certificate management]
+PII handling: [identification, masking, pseudonymization, retention limits]
+Data residency: [geographic constraints, cross-border transfer rules]
+Backup encryption: [separate key, recovery testing frequency]
+```
+
+### Compliance Requirements
+```
+NFR-COMP-NNN: [Compliance Requirement]
+Framework: [GDPR, SOC 2, HIPAA, PCI-DSS, ISO 27001]
+Scope: [which components/data are in scope]
+Controls: [specific controls required — access logging, encryption, retention]
+Audit frequency: [continuous, quarterly, annual]
+Evidence requirements: [what documentation/logs must be maintained]
+```
+
+### Security Anti-Requirements
+Explicitly exclude unreasonable expectations:
+- "The system should be secure" (not measurable)
+- "No vulnerabilities" (impossible — define acceptable risk)
+- "Military-grade encryption" (undefined — specify algorithm and key length)
+
+Replace with: "All API endpoints require JWT authentication with RS256 signing. Access tokens expire after 15 minutes. Refresh tokens expire after 7 days and are single-use."