specky-sdd 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -5,6 +5,99 @@ All notable changes to Specky are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.2.0] - 2026-04-12
+
+### Enterprise Security Hardening
+
+#### Rate Limiting (opt-in)
+- **`RateLimiter` service**: Token bucket algorithm — no external deps, pure TypeScript
+- HTTP transport now supports `rate_limit.enabled: true` in `.specky/config.yml`
+- Config: `max_requests_per_minute` (default 60), `burst` (default 10)
+- Returns HTTP 429 with `Retry-After` header when limit exceeded
+- stdio mode bypasses rate limiting by design (single-session, process-isolated)
+
+#### State File Integrity
+- **`StateMachine.saveState()`** now writes HMAC-SHA256 signature to `.sdd-state.json.sig`
+- **`StateMachine.loadState()`** verifies signature on every load — tamper warning to stderr on mismatch
+- Key: `SDD_STATE_KEY` env var, or derived from workspace path using SHA-256
+- Missing `.sig` treated as unverified (no warning) — backward-compatible with pre-v3.2.0 state files
+
+#### Enhanced Audit Logger
+- **Hash-chaining**: every `AuditEntry` includes `previous_hash` (SHA-256 of previous line, seed `specky-audit-v1`)
+- **Log rotation**: rotates `.audit.jsonl` → `.audit.jsonl.1` when `audit.max_file_size_mb` exceeded (default 10 MB)
+- **Syslog export**: RFC 5424 format written to `.audit.syslog` when `audit.export_format: syslog`
+- **OTLP stub**: `audit.export_format: otlp` logs placeholder — implementation in next release
+
+#### RBAC Foundation (opt-in)
+- **`RbacEngine` service**: `viewer` / `contributor` / `admin` roles; disabled by default
+- **`sdd_check_access`** (NEW tool #57): Returns active role, per-tool access check, full role summary
+- Role enforcement via `SDD_ROLE` env var or `rbac.default_role` in config
+- Viewer: read-only tools only; Contributor: all except `sdd_create_pr`; Admin: all 57 tools
+- Config: `rbac.enabled: true`, `rbac.default_role: contributor`
+
+#### Config Extension
+- `.specky/config.yml` now supports nested blocks: `rate_limit:`, `audit:`, `rbac:`
+- Parser upgraded to handle indented YAML child keys (dot-notation flattening)
+- All new options opt-in with safe defaults — existing behavior unchanged from v3.1.0
+
+### NPM-as-Default Migration
+- Global install (`npm install -g specky-sdd`) is now the recommended installation method
+- npx retained as an "alternative" option for per-workspace and convenience use
+- All docs updated: README.md, GETTING-STARTED.md, SYSTEM-DESIGN.md, ONBOARDING.md, SECURITY.md
+- New "Enterprise Installation Methods" section in GETTING-STARTED.md
+- New "NPX Supply Chain Risk" + "MCP Security Framework Compliance" sections in SECURITY.md
+
+### Security Documentation
+- **CoSAI MCP Security White Paper** — full T-01 through T-12 threat coverage table in SECURITY.md
+- **OWASP MCP Top 10** — M1 through M10 coverage table in SECURITY.md
+
+### Tests
+- 561 tests (+54): `rate-limiter.test.ts` (11), `state-integrity.test.ts` (8), `audit-enhanced.test.ts` (12), `rbac-engine.test.ts` (15), plus existing suite maintained at 100%
+
+---
+
+## [3.1.0] - 2026-04-12
+
+### Intelligence Layer (Specs 003–007)
+
+#### Model Routing Guidance (Spec 003)
+- **`sdd_model_routing`** (NEW tool #54): Returns the full 10-phase model routing decision table with optimal model, mode, extended thinking settings, arXiv evidence, and cost savings calculator
+- **`model_routing_hint`** field added to ALL 55 tool responses via `buildToolResponse()` — every response now tells the AI client which model to use for the current phase
+- Complexity override: `implement`/`design` phases with >10 files escalate to Opus automatically
+- `ModelRoutingEngine` service with empirically-grounded ROUTING_TABLE (arXiv:2601.08419)
+
+#### Context Tiering (Spec 004)
+- **`sdd_context_status`** (NEW tool #55): Returns Hot/Domain/Cold tier assignment for all spec artifacts with estimated token savings
+- **`context_load_summary`** field added to ALL 55 tool responses — shows which files are loaded per call
+- `ContextTieringEngine` service: CONSTITUTION.md=Hot, SPEC/DESIGN/TASKS=Domain, ANALYSIS/CHECKLIST/etc=Cold
+- Token estimation: `Math.ceil(content.length / 4)` — matches GPT/Claude tokenization heuristic
+
+#### Cognitive Debt Metrics (Spec 005)
+- **`cognitive_debt`** field in `sdd_metrics` and `sdd_get_status` responses (when gate history available)
+- Gate instrumentation in `sdd_advance_phase`: records mtime-based modified/unmodified detection per gate
+- `CognitiveDebtEngine` service: LGTM-without-modification rate as cognitive surrender signal; score = `(lgtm_rate × 0.6) + (delta_normalized × 0.4)`, labels: healthy/caution/high_risk
+- Warning shown in `sdd_advance_phase` response when unmodified approval is detected
+
+#### Verified Test Loop (Spec 006)
+- **`TestResultParser`** service: auto-detects and parses Vitest JSON, pytest JSON, and JUnit XML into normalized `TestResult[]`
+- **`TestTraceabilityMapper`** service: maps test names to REQ-XXX IDs via `// REQ-XXX` comment convention, builds per-requirement coverage report and failure details with `suggested_fix_prompt`
+- `sdd_verify_tests` enhanced: adds `enhanced_coverage` (per-requirement breakdown) and `failure_details` to response when parsers are wired
+- JUnit XML parser bug fixed: self-closing `<testcase .../>` was greedily consumed by open-tag alternative, merging two testcases; fixed with negative lookbehind `(?<!\/)`
+
+#### Intent Drift Detection (Spec 007)
+- **`intent_drift`** report in `sdd_check_sync` and `sdd_metrics` responses
+- **`drift_amendment_suggestion`** in `sdd_amend` response when last drift score > 40 — lists orphaned constitutional principles with recommended spec actions
+- `IntentDriftEngine` service: extracts principles from CONSTITUTION.md `## Article` sections, keyword-overlap coverage detection (≥2 keywords threshold), trend analysis (improving/stable/worsening) over last 3 DriftSnapshots
+- `drift_history` stored in `.sdd-state.json` (FIFO, max 100 entries)
+
+### Stats
+- **56 tools** (was 53, corrected to 56 — sdd_metrics, sdd_validate_ears, sdd_check_ecosystem were already implemented but undercounted): +sdd_model_routing, +sdd_context_status, count reconciled
+- **24 services** (was 18): +ModelRoutingEngine, +ContextTieringEngine, +CognitiveDebtEngine, +IntentDriftEngine, +TestResultParser, +TestTraceabilityMapper
+- **507 unit tests** across 30 test files (was 321 across 22 files)
+- All 7 specs (001–007) at ≥93% acceptance criteria coverage
+
+---
+
 ## [3.0.0] - 2026-03-26
 
 ### Pipeline Validation & Enforcement
@@ -105,7 +198,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `sdd_verify_tests` tool — verifies test results JSON against specification requirements, reports traceability coverage
 - `.specky/config.yml` support — project-local configuration for templates path, default framework, compliance frameworks, audit toggle
 - `src/config.ts` — centralized configuration loader with simple YAML parsing
-- MCP integration test (`tests/integration/pipeline-e2e.test.ts`) — end-to-end pipeline validation with real FileManager
+- MCP integration test (`tests/integration/pipeline-e2e.test.ts`) — full pipeline validation with real FileManager
 - Unit tests for 6 additional services: DocGenerator, GitManager, IacGenerator, WorkItemExporter, TranscriptParser, DocumentConverter
 - OpenSSF Scorecard workflow (`.github/workflows/scorecard.yml`)
 - SBOM generation (CycloneDX) in CI pipeline