More clean up

docs/traceability-ci.md

@@ -0,0 +1,288 @@
+# Requirement Traceability CI/CD Pipeline
+
+This document explains the automated requirement traceability validation system for JellyTau.
+
+## Overview
+
+The CI/CD pipeline automatically validates that code changes are properly traced to requirements. This ensures:
+- ✅ Requirements are implemented with clear traceability
+- ✅ No requirement coverage regressions
+- ✅ Code changes are linked to specific requirements
+- ✅ Quality metrics are tracked over time
+
+## Gitea Actions Workflows
+
+Two workflows are configured in `.gitea/workflows/`:
+
+### 1. `traceability-check.yml` (Primary - Recommended)
+Gitea-native workflow with:
+- ✅ Automatic trace extraction
+- ✅ Coverage validation against minimum threshold (50%)
+- ✅ Modified file checking
+- ✅ Artifact preservation
+- ✅ Summary reports
+
+**Runs on:** Every push and pull request
+
+### 2. `traceability.yml` (Alternative)
+GitHub-compatible workflow with additional features:
+- Pull request comments with coverage stats
+- GitHub-specific integrations
+
+## What Gets Validated
+
+### 1. Trace Extraction
+```bash
+bun run traces:json > traces-report.json
+```
+Extracts all TRACES comments from:
+- TypeScript files (`src/**/*.ts`)
+- Svelte components (`src/**/*.svelte`)
+- Rust code (`src-tauri/src/**/*.rs`)
+- Test files
+
+### 2. Coverage Thresholds
+The workflow checks:
+- **Minimum overall coverage:** 50% (57+ requirements traced)
+- **Requirements by type:**
+  - UR (User): 23+ of 39
+  - IR (Integration): 5+ of 24
+  - DR (Development): 28+ of 48
+  - JA (Jellyfin API): 0+ of 3
+
+If coverage drops below threshold, the workflow **fails** and blocks merge.
+
+### 3. Modified File Checking
+On pull requests, the workflow:
+1. Detects all changed TypeScript/Svelte/Rust files
+2. Warns if new/modified files lack TRACES comments
+3. Suggests the TRACES format for missing comments
+
+## How to Add Traces to New Code
+
+When you add new code or modify existing code, include TRACES comments:
+
+### TypeScript/Svelte Example
+```typescript
+// TRACES: UR-005, UR-026 | DR-029
+export function handlePlayback() {
+  // Implementation...
+}
+```
+
+### Rust Example
+```rust
+/// TRACES: UR-005 | DR-001
+pub fn player_state_changed(state: PlayerState) {
+    // Implementation...
+}
+```
+
+### Test Example
+```rust
+// TRACES: UR-005 | DR-001 | UT-026, UT-027
+#[cfg(test)]
+mod tests {
+    // Tests...
+}
+```
+
+## TRACES Format
+
+```
+TRACES: [UR-###, ...] | [IR-###, ...] | [DR-###, ...] | [JA-###, ...]
+```
+
+- `UR-###` - User Requirements (features users see)
+- `IR-###` - Integration Requirements (API/platform integration)
+- `DR-###` - Development Requirements (internal architecture)
+- `JA-###` - Jellyfin API Requirements (Jellyfin API usage)
+
+**Examples:**
+- `// TRACES: UR-005` - Single requirement
+- `// TRACES: UR-005, UR-026` - Multiple of same type
+- `// TRACES: UR-005 | DR-029` - Multiple types
+- `// TRACES: UR-005, UR-026 | DR-001, DR-029 | UT-001` - Complex
+
+## Workflow Behavior
+
+### On Push to Main Branch
+1. ✅ Extracts all traces from code
+2. ✅ Validates coverage is >= 50%
+3. ✅ Generates full traceability report
+4. ✅ Saves report as artifact
+
+### On Pull Request
+1. ✅ Extracts all traces
+2. ✅ Validates coverage >= 50%
+3. ✅ Checks modified files for TRACES
+4. ✅ Warns if new code lacks TRACES
+5. ✅ Suggests proper format
+6. ✅ Generates report artifact
+
+### Failure Scenarios
+The workflow **fails** (blocks merge) if:
+- Coverage drops below 50%
+- JSON extraction fails
+- Invalid trace format
+
+The workflow **warns** (but doesn't block) if:
+- New files lack TRACES comments
+- Coverage drops (but still above threshold)
+
+## Viewing Reports
+
+### In Gitea Actions UI
+1. Go to **Actions** tab
+2. Click the **Traceability Validation** workflow run
+3. Download **traceability-reports** artifact
+4. View:
+   - `traces-report.json` - Raw trace data
+   - `docs/traceability.md` - Formatted report
+
+### Locally
+```bash
+# Extract current traces
+bun run traces:json | jq '.byType'
+
+# Generate full report
+bun run traces:markdown
+cat docs/traceability.md
+```
+
+## Coverage Goals
+
+### Current Status
+- Overall: 51% (56/114)
+- UR: 59% (23/39)
+- IR: 21% (5/24)
+- DR: 58% (28/48)
+- JA: 0% (0/3)
+
+### Targets
+- **Short term** (Sprint): Maintain ≥50% overall
+- **Medium term** (Month): Reach 70% overall coverage
+- **Long term** (Release): Reach 90% coverage with focus on:
+  - IR requirements (API clients)
+  - JA requirements (Jellyfin API endpoints)
+  - Remaining UR/DR requirements
+
+## Improving Coverage
+
+### For Missing User Requirements (UR)
+1. Review [README.md](../README.md) for unimplemented features
+2. Add TRACES to code that implements them
+3. Focus on high-priority features (High/Medium priority)
+
+### For Missing Integration Requirements (IR)
+1. Add TRACES to Jellyfin API client methods
+2. Add TRACES to platform-specific backends (Android/Linux)
+3. Link to corresponding Jellyfin API endpoints
+
+### For Missing Development Requirements (DR)
+1. Add TRACES to UI components in `src/lib/components/`
+2. Add TRACES to composables in `src/lib/composables/`
+3. Add TRACES to player backend in `src-tauri/src/player/`
+
+### For Jellyfin API Requirements (JA)
+1. Add TRACES to Jellyfin API wrapper methods
+2. Document which endpoints map to which requirements
+3. Link to Jellyfin API documentation
+
+## Example PR Checklist
+
+When submitting a pull request:
+
+- [ ] All new code has TRACES comments linking to requirements
+- [ ] TRACES format is correct: `// TRACES: UR-001 | DR-002`
+- [ ] Workflow passes (coverage ≥ 50%)
+- [ ] No coverage regressions
+- [ ] Artifact traceability report was generated
+
+## Troubleshooting
+
+### "Coverage below minimum threshold"
+**Problem:** Workflow fails with coverage < 50%
+
+**Solution:**
+1. Run `bun run traces:json` locally
+2. Check which requirements are traced
+3. Add TRACES to untraced code sections
+4. Re-run extraction to verify
+
+### "New files without TRACES"
+**Problem:** Workflow warns about new files lacking TRACES
+
+**Solution:**
+1. Add TRACES comments to all new code
+2. Format: `// TRACES: UR-001 | DR-002`
+3. Map code to specific requirements from README.md
+4. Re-push
+
+### "Invalid JSON format"
+**Problem:** Trace extraction produces invalid JSON
+
+**Solution:**
+1. Check for malformed TRACES comments
+2. Run locally: `bun run traces:json`
+3. Look for parsing errors
+4. Fix and retry
+
+## Integration with Development
+
+### Before Committing
+```bash
+# Check your traces
+bun run traces:json | jq '.byType'
+
+# Regenerate report
+bun run traces:markdown
+
+# Verify traces syntax
+grep "TRACES:" src/**/*.ts src/**/*.rs
+```
+
+### In Your IDE
+Add a file watcher to regenerate traces on save:
+```json
+{
+  "fileWatcher.watchPatterns": [
+    "src/**/*.ts",
+    "src/**/*.svelte",
+    "src-tauri/src/**/*.rs"
+  ],
+  "fileWatcher.command": "bun run traces:markdown"
+}
+```
+
+### Git Hooks
+Add a pre-push hook to validate traces:
+
+```bash
+#!/bin/bash
+# .git/hooks/pre-push
+bun run traces:json > /dev/null
+if [ $? -ne 0 ]; then
+  echo "❌ Invalid TRACES format"
+  exit 1
+fi
+```
+
+## References
+
+- [Extract Traces Script](../scripts/README.md#extract-tracests)
+- [Requirements Specification](../README.md#requirements-specification)
+- [Traceability Matrix](./traceability.md)
+- [Gitea Actions Documentation](https://docs.gitea.io/en-us/actions/)
+
+## Support
+
+For issues or questions:
+1. Check this document
+2. Review example traces in `src/lib/stores/`
+3. Check existing TRACES comments for format
+4. Review workflow logs in Gitea Actions
+
+---
+
+**Last Updated:** 2026-02-13