@diottodev/runic 1.0.0 → 1.1.0

package/engineering/skills/tc-tracker/scripts/tc_validator.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""TC Validator — Validate a TC record or registry against the schema and state machine.
+
+Enforces:
+  * Schema shape (required fields, types, enum values)
+  * State machine transitions (planned -> in_progress -> implemented -> tested -> deployed)
+  * Sequential R<n> revision IDs and T<n> test IDs
+  * TC ID format (TC-NNN-MM-DD-YY-slug)
+  * Sub-TC ID format (TC-NNN.A or TC-NNN.A.N)
+  * Approval consistency (approved=true requires approved_by + approved_date)
+
+Usage:
+    python3 tc_validator.py --record path/to/tc_record.json
+    python3 tc_validator.py --registry path/to/tc_registry.json
+    python3 tc_validator.py --record path/to/tc_record.json --json
+
+Exit codes:
+    0 = valid
+    1 = validation errors
+    2 = file not found / JSON parse error / bad CLI args
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+
+VALID_STATUSES = ("planned", "in_progress", "blocked", "implemented", "tested", "deployed")
+
+VALID_TRANSITIONS = {
+    "planned":     ["in_progress", "blocked"],
+    "in_progress": ["blocked", "implemented"],
+    "blocked":     ["in_progress", "planned"],
+    "implemented": ["tested", "in_progress"],
+    "tested":      ["deployed", "in_progress"],
+    "deployed":    ["in_progress"],
+}
+
+VALID_SCOPES = ("feature", "bugfix", "refactor", "infrastructure", "documentation", "hotfix", "enhancement")
+VALID_PRIORITIES = ("critical", "high", "medium", "low")
+VALID_FILE_ACTIONS = ("created", "modified", "deleted", "renamed")
+VALID_TEST_STATUSES = ("pending", "pass", "fail", "skip", "blocked")
+VALID_EVIDENCE_TYPES = ("log_snippet", "screenshot", "file_reference", "command_output")
+VALID_FIELD_CHANGE_ACTIONS = ("set", "changed", "added", "removed")
+VALID_PLATFORMS = ("claude_code", "claude_web", "api", "other")
+VALID_COVERAGE = ("none", "partial", "full")
+VALID_FILE_IN_PROGRESS_STATES = ("editing", "needs_review", "partially_done", "ready")
+
+TC_ID_PATTERN = re.compile(r"^TC-\d{3}-\d{2}-\d{2}-\d{2}-[a-z0-9]+(-[a-z0-9]+)*$")
+SUB_TC_PATTERN = re.compile(r"^TC-\d{3}\.[A-Z](\.\d+)?$")
+REVISION_ID_PATTERN = re.compile(r"^R(\d+)$")
+TEST_ID_PATTERN = re.compile(r"^T(\d+)$")
+
+
+def _enum(value, valid, name):
+    if value not in valid:
+        return [f"Field '{name}' has invalid value '{value}'. Must be one of: {', '.join(str(v) for v in valid)}"]
+    return []
+
+
+def _string(value, name, min_length=0, max_length=None):
+    errors = []
+    if not isinstance(value, str):
+        return [f"Field '{name}' must be a string, got {type(value).__name__}"]
+    if len(value) < min_length:
+        errors.append(f"Field '{name}' must be at least {min_length} characters, got {len(value)}")
+    if max_length is not None and len(value) > max_length:
+        errors.append(f"Field '{name}' must be at most {max_length} characters, got {len(value)}")
+    return errors
+
+
+def _iso(value, name):
+    if value is None:
+        return []
+    if not isinstance(value, str):
+        return [f"Field '{name}' must be an ISO 8601 datetime string"]
+    try:
+        datetime.fromisoformat(value)
+    except ValueError:
+        return [f"Field '{name}' is not a valid ISO 8601 datetime: '{value}'"]
+    return []
+
+
+def _required(record, fields, prefix=""):
+    errors = []
+    for f in fields:
+        if f not in record:
+            path = f"{prefix}.{f}" if prefix else f
+            errors.append(f"Missing required field: '{path}'")
+    return errors
+
+
+def validate_tc_id(tc_id):
+    """Validate a TC identifier."""
+    if not isinstance(tc_id, str):
+        return [f"tc_id must be a string, got {type(tc_id).__name__}"]
+    if not TC_ID_PATTERN.match(tc_id):
+        return [f"tc_id '{tc_id}' does not match pattern TC-NNN-MM-DD-YY-slug"]
+    return []
+
+
+def validate_state_transition(current, new):
+    """Validate a state machine transition. Same-status is a no-op."""
+    errors = []
+    if current not in VALID_STATUSES:
+        errors.append(f"Current status '{current}' is invalid")
+    if new not in VALID_STATUSES:
+        errors.append(f"New status '{new}' is invalid")
+    if errors:
+        return errors
+    if current == new:
+        return []
+    allowed = VALID_TRANSITIONS.get(current, [])
+    if new not in allowed:
+        return [f"Invalid transition '{current}' -> '{new}'. Allowed from '{current}': {', '.join(allowed) or 'none'}"]
+    return []
+
+
+def validate_tc_record(record):
+    """Validate a TC record dict against the schema."""
+    errors = []
+    if not isinstance(record, dict):
+        return [f"TC record must be a JSON object, got {type(record).__name__}"]
+
+    top_required = [
+        "tc_id", "title", "status", "priority", "created", "updated",
+        "created_by", "project", "description", "files_affected",
+        "revision_history", "test_cases", "approval", "session_context",
+        "tags", "related_tcs", "notes", "metadata",
+    ]
+    errors.extend(_required(record, top_required))
+
+    if "tc_id" in record:
+        errors.extend(validate_tc_id(record["tc_id"]))
+    if "title" in record:
+        errors.extend(_string(record["title"], "title", 5, 120))
+    if "status" in record:
+        errors.extend(_enum(record["status"], VALID_STATUSES, "status"))
+    if "priority" in record:
+        errors.extend(_enum(record["priority"], VALID_PRIORITIES, "priority"))
+    for ts in ("created", "updated"):
+        if ts in record:
+            errors.extend(_iso(record[ts], ts))
+    if "created_by" in record:
+        errors.extend(_string(record["created_by"], "created_by", 1))
+    if "project" in record:
+        errors.extend(_string(record["project"], "project", 1))
+
+    desc = record.get("description")
+    if isinstance(desc, dict):
+        errors.extend(_required(desc, ["summary", "motivation", "scope"], "description"))
+        if "summary" in desc:
+            errors.extend(_string(desc["summary"], "description.summary", 10))
+        if "motivation" in desc:
+            errors.extend(_string(desc["motivation"], "description.motivation", 1))
+        if "scope" in desc:
+            errors.extend(_enum(desc["scope"], VALID_SCOPES, "description.scope"))
+    elif "description" in record:
+        errors.append("Field 'description' must be an object")
+
+    files = record.get("files_affected")
+    if isinstance(files, list):
+        for i, f in enumerate(files):
+            prefix = f"files_affected[{i}]"
+            if not isinstance(f, dict):
+                errors.append(f"{prefix} must be an object")
+                continue
+            errors.extend(_required(f, ["path", "action"], prefix))
+            if "action" in f:
+                errors.extend(_enum(f["action"], VALID_FILE_ACTIONS, f"{prefix}.action"))
+    elif "files_affected" in record:
+        errors.append("Field 'files_affected' must be an array")
+
+    revs = record.get("revision_history")
+    if isinstance(revs, list):
+        if len(revs) < 1:
+            errors.append("revision_history must have at least 1 entry")
+        for i, rev in enumerate(revs):
+            prefix = f"revision_history[{i}]"
+            if not isinstance(rev, dict):
+                errors.append(f"{prefix} must be an object")
+                continue
+            errors.extend(_required(rev, ["revision_id", "timestamp", "author", "summary"], prefix))
+            rid = rev.get("revision_id")
+            if isinstance(rid, str):
+                m = REVISION_ID_PATTERN.match(rid)
+                if not m:
+                    errors.append(f"{prefix}.revision_id '{rid}' must match R<n>")
+                elif int(m.group(1)) != i + 1:
+                    errors.append(f"{prefix}.revision_id is '{rid}' but expected 'R{i + 1}' (must be sequential)")
+            if "timestamp" in rev:
+                errors.extend(_iso(rev["timestamp"], f"{prefix}.timestamp"))
+    elif "revision_history" in record:
+        errors.append("Field 'revision_history' must be an array")
+
+    tests = record.get("test_cases")
+    if isinstance(tests, list):
+        for i, tc in enumerate(tests):
+            prefix = f"test_cases[{i}]"
+            if not isinstance(tc, dict):
+                errors.append(f"{prefix} must be an object")
+                continue
+            errors.extend(_required(tc, ["test_id", "title", "procedure", "expected_result", "status"], prefix))
+            tid = tc.get("test_id")
+            if isinstance(tid, str):
+                m = TEST_ID_PATTERN.match(tid)
+                if not m:
+                    errors.append(f"{prefix}.test_id '{tid}' must match T<n>")
+                elif int(m.group(1)) != i + 1:
+                    errors.append(f"{prefix}.test_id is '{tid}' but expected 'T{i + 1}' (must be sequential)")
+            if "status" in tc:
+                errors.extend(_enum(tc["status"], VALID_TEST_STATUSES, f"{prefix}.status"))
+
+    appr = record.get("approval")
+    if isinstance(appr, dict):
+        errors.extend(_required(appr, ["approved", "test_coverage_status"], "approval"))
+        if appr.get("approved") is True:
+            if not appr.get("approved_by"):
+                errors.append("approval.approved_by is required when approval.approved is true")
+            if not appr.get("approved_date"):
+                errors.append("approval.approved_date is required when approval.approved is true")
+        if "test_coverage_status" in appr:
+            errors.extend(_enum(appr["test_coverage_status"], VALID_COVERAGE, "approval.test_coverage_status"))
+    elif "approval" in record:
+        errors.append("Field 'approval' must be an object")
+
+    ctx = record.get("session_context")
+    if isinstance(ctx, dict):
+        errors.extend(_required(ctx, ["current_session"], "session_context"))
+        cs = ctx.get("current_session")
+        if isinstance(cs, dict):
+            errors.extend(_required(cs, ["session_id", "platform", "model", "started"], "session_context.current_session"))
+            if "platform" in cs:
+                errors.extend(_enum(cs["platform"], VALID_PLATFORMS, "session_context.current_session.platform"))
+            if "started" in cs:
+                errors.extend(_iso(cs["started"], "session_context.current_session.started"))
+
+    meta = record.get("metadata")
+    if isinstance(meta, dict):
+        errors.extend(_required(meta, ["project", "created_by", "last_modified_by", "last_modified"], "metadata"))
+        if "last_modified" in meta:
+            errors.extend(_iso(meta["last_modified"], "metadata.last_modified"))
+
+    return errors
+
+
+def validate_registry(registry):
+    """Validate a TC registry dict."""
+    errors = []
+    if not isinstance(registry, dict):
+        return [f"Registry must be an object, got {type(registry).__name__}"]
+    errors.extend(_required(registry, ["project_name", "created", "updated", "next_tc_number", "records", "statistics"]))
+    if "next_tc_number" in registry:
+        v = registry["next_tc_number"]
+        if not isinstance(v, int) or v < 1:
+            errors.append(f"next_tc_number must be a positive integer, got {v}")
+    if isinstance(registry.get("records"), list):
+        for i, rec in enumerate(registry["records"]):
+            prefix = f"records[{i}]"
+            if not isinstance(rec, dict):
+                errors.append(f"{prefix} must be an object")
+                continue
+            errors.extend(_required(rec, ["tc_id", "title", "status", "scope", "priority", "created", "updated", "path"], prefix))
+            if "status" in rec:
+                errors.extend(_enum(rec["status"], VALID_STATUSES, f"{prefix}.status"))
+            if "scope" in rec:
+                errors.extend(_enum(rec["scope"], VALID_SCOPES, f"{prefix}.scope"))
+            if "priority" in rec:
+                errors.extend(_enum(rec["priority"], VALID_PRIORITIES, f"{prefix}.priority"))
+    return errors
+
+
+def slugify(text):
+    """Convert text to a kebab-case slug."""
+    text = text.lower().strip()
+    text = re.sub(r"[^a-z0-9\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    text = re.sub(r"-+", "-", text)
+    return text.strip("-")
+
+
+def compute_registry_statistics(records):
+    """Recompute registry statistics from the records array."""
+    stats = {
+        "total": len(records),
+        "by_status": {s: 0 for s in VALID_STATUSES},
+        "by_scope": {s: 0 for s in VALID_SCOPES},
+        "by_priority": {p: 0 for p in VALID_PRIORITIES},
+    }
+    for rec in records:
+        for key, bucket in (("status", "by_status"), ("scope", "by_scope"), ("priority", "by_priority")):
+            v = rec.get(key, "")
+            if v in stats[bucket]:
+                stats[bucket][v] += 1
+    return stats
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Validate a TC record or registry.")
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument("--record", help="Path to tc_record.json")
+    group.add_argument("--registry", help="Path to tc_registry.json")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+
+    target = args.record or args.registry
+    path = Path(target)
+    if not path.exists():
+        msg = f"File not found: {path}"
+        print(json.dumps({"status": "error", "error": msg}) if args.json else f"ERROR: {msg}")
+        return 2
+
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        msg = f"Invalid JSON in {path}: {e}"
+        print(json.dumps({"status": "error", "error": msg}) if args.json else f"ERROR: {msg}")
+        return 2
+
+    errors = validate_registry(data) if args.registry else validate_tc_record(data)
+
+    if args.json:
+        result = {
+            "status": "valid" if not errors else "invalid",
+            "file": str(path),
+            "kind": "registry" if args.registry else "record",
+            "error_count": len(errors),
+            "errors": errors,
+        }
+        print(json.dumps(result, indent=2))
+    else:
+        if errors:
+            print(f"VALIDATION ERRORS ({len(errors)}):")
+            for i, err in enumerate(errors, 1):
+                print(f"  {i}. {err}")
+        else:
+            print("VALID")
+
+    return 1 if errors else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/skills/tech-debt-tracker/README.md

@@ -0,0 +1,308 @@
+# Tech Debt Tracker
+
+A comprehensive technical debt management system that helps engineering teams identify, prioritize, and track technical debt across codebases. This skill provides three interconnected tools for a complete debt management workflow.
+
+## Overview
+
+Technical debt is like financial debt - it compounds over time and reduces team velocity if not managed systematically. This skill provides:
+
+- **Automated Debt Detection**: Scan codebases to identify various types of technical debt
+- **Intelligent Prioritization**: Use proven frameworks to prioritize debt based on business impact
+- **Trend Analysis**: Track debt evolution over time with executive-friendly dashboards
+
+## Tools
+
+### 1. Debt Scanner (`debt_scanner.py`)
+
+Scans codebases to automatically detect technical debt signals using AST parsing for Python and regex patterns for other languages.
+
+**Features:**
+- Detects 15+ types of technical debt (large functions, complexity, duplicates, security issues, etc.)
+- Multi-language support (Python, JavaScript, Java, C#, Go, etc.)
+- Configurable thresholds and rules
+- Dual output: JSON for tools, human-readable for reports
+
+**Usage:**
+```bash
+# Basic scan
+python scripts/debt_scanner.py /path/to/codebase
+
+# With custom config and output
+python scripts/debt_scanner.py /path/to/codebase --config config.json --output report.json
+
+# Different output formats
+python scripts/debt_scanner.py /path/to/codebase --format both
+```
+
+### 2. Debt Prioritizer (`debt_prioritizer.py`)
+
+Takes debt inventory and creates prioritized backlog using proven prioritization frameworks.
+
+**Features:**
+- Multiple prioritization frameworks (Cost of Delay, WSJF, RICE)
+- Business impact analysis with ROI calculations  
+- Sprint allocation recommendations
+- Effort estimation with risk adjustment
+- Executive and engineering reports
+
+**Usage:**
+```bash
+# Basic prioritization
+python scripts/debt_prioritizer.py debt_inventory.json
+
+# Custom framework and team size
+python scripts/debt_prioritizer.py inventory.json --framework wsjf --team-size 8
+
+# Sprint capacity planning
+python scripts/debt_prioritizer.py inventory.json --sprint-capacity 80 --output backlog.json
+```
+
+### 3. Debt Dashboard (`debt_dashboard.py`)
+
+Analyzes historical debt data to provide trend analysis, health scoring, and executive reporting.
+
+**Features:**
+- Health score trending over time
+- Debt velocity analysis (accumulation vs resolution)
+- Executive summary with business impact
+- Forecasting based on current trends
+- Strategic recommendations
+
+**Usage:**
+```bash
+# Single directory of scans
+python scripts/debt_dashboard.py --input-dir ./debt_scans/
+
+# Multiple specific files
+python scripts/debt_dashboard.py scan1.json scan2.json scan3.json
+
+# Custom analysis period
+python scripts/debt_dashboard.py data.json --period quarterly --team-size 6
+```
+
+## Quick Start
+
+### 1. Scan Your Codebase
+
+```bash
+# Scan your project
+python scripts/debt_scanner.py ~/my-project --output initial_scan.json
+
+# Review the results
+python scripts/debt_scanner.py ~/my-project --format text
+```
+
+### 2. Prioritize Your Debt
+
+```bash
+# Create prioritized backlog
+python scripts/debt_prioritizer.py initial_scan.json --output backlog.json
+
+# View sprint recommendations
+python scripts/debt_prioritizer.py initial_scan.json --format text
+```
+
+### 3. Track Over Time
+
+```bash
+# After multiple scans, analyze trends
+python scripts/debt_dashboard.py scan1.json scan2.json scan3.json --output dashboard.json
+
+# Generate executive report
+python scripts/debt_dashboard.py --input-dir ./scans/ --format text
+```
+
+## Configuration
+
+### Scanner Configuration
+
+Create `config.json` to customize detection rules:
+
+```json
+{
+  "max_function_length": 50,
+  "max_complexity": 10,
+  "max_nesting_depth": 4,
+  "ignore_patterns": ["*.test.js", "build/", "node_modules/"],
+  "file_extensions": {
+    "python": [".py"],
+    "javascript": [".js", ".jsx", ".ts", ".tsx"]
+  }
+}
+```
+
+### Team Configuration
+
+Adjust tools for your team size and sprint capacity:
+
+```bash
+# 8-person team with 2-week sprints
+python scripts/debt_prioritizer.py inventory.json --team-size 8 --sprint-capacity 160
+```
+
+## Sample Data
+
+The `assets/` directory contains sample data for testing:
+
+- `sample_codebase/`: Example codebase with various debt types
+- `sample_debt_inventory.json`: Example debt inventory
+- `historical_debt_*.json`: Sample historical data for trending
+
+Try the tools on sample data:
+
+```bash
+# Test scanner
+python scripts/debt_scanner.py assets/sample_codebase
+
+# Test prioritizer  
+python scripts/debt_prioritizer.py assets/sample_debt_inventory.json
+
+# Test dashboard
+python scripts/debt_dashboard.py assets/historical_debt_*.json
+```
+
+## Understanding the Output
+
+### Health Score (0-100)
+
+- **85-100**: Excellent - Minimal debt, sustainable practices
+- **70-84**: Good - Manageable debt level, some attention needed
+- **55-69**: Fair - Debt accumulating, requires focused effort
+- **40-54**: Poor - High debt level, impacts productivity
+- **0-39**: Critical - Immediate action required
+
+### Priority Levels
+
+- **Critical**: Security issues, blocking problems (fix immediately)
+- **High**: Significant impact on quality or velocity (next sprint)
+- **Medium**: Moderate impact, plan for upcoming work (next quarter)
+- **Low**: Minor issues, fix opportunistically (when convenient)
+
+### Debt Categories
+
+- **Code Quality**: Large functions, complexity, duplicates
+- **Architecture**: Design issues, coupling problems
+- **Security**: Vulnerabilities, hardcoded secrets
+- **Testing**: Missing tests, poor coverage
+- **Documentation**: Missing or outdated docs
+- **Dependencies**: Outdated packages, license issues
+
+## Integration with Development Workflow
+
+### CI/CD Integration
+
+Add debt scanning to your CI pipeline:
+
+```bash
+# In your CI script
+python scripts/debt_scanner.py . --output ci_scan.json
+# Compare with baseline, fail build if critical issues found
+```
+
+### Sprint Planning
+
+1. **Weekly**: Run scanner to detect new debt
+2. **Sprint Planning**: Use prioritizer for debt story sizing
+3. **Monthly**: Generate dashboard for trend analysis
+4. **Quarterly**: Executive review with strategic recommendations
+
+### Code Review Integration
+
+Use scanner output to focus code reviews:
+
+```bash
+# Scan PR branch
+python scripts/debt_scanner.py . --output pr_scan.json
+
+# Compare with main branch baseline
+# Focus review on areas with new debt
+```
+
+## Best Practices
+
+### Debt Management Strategy
+
+1. **Prevention**: Use scanner in CI to catch debt early
+2. **Prioritization**: Always use business impact for priority
+3. **Allocation**: Reserve 15-20% sprint capacity for debt work
+4. **Measurement**: Track health score and velocity impact
+5. **Communication**: Use dashboard reports for stakeholders
+
+### Common Pitfalls to Avoid
+
+- **Analysis Paralysis**: Don't spend too long on perfect prioritization
+- **Technical Focus Only**: Always consider business impact
+- **Inconsistent Application**: Ensure all teams use same approach
+- **Ignoring Trends**: Pay attention to debt accumulation rate
+- **All-or-Nothing**: Incremental debt reduction is better than none
+
+### Success Metrics
+
+- **Health Score Improvement**: Target 5+ point quarterly improvement
+- **Velocity Impact**: Keep debt velocity impact below 20%
+- **Team Satisfaction**: Survey developers on code quality satisfaction
+- **Incident Reduction**: Track correlation between debt and production issues
+
+## Advanced Usage
+
+### Custom Debt Types
+
+Extend the scanner for organization-specific debt patterns:
+
+1. Add patterns to `config.json`
+2. Modify detection logic in scanner
+3. Update categorization in prioritizer
+
+### Integration with External Tools
+
+- **Jira/GitHub**: Import debt items as tickets
+- **SonarQube**: Combine with static analysis metrics
+- **APM Tools**: Correlate debt with performance metrics
+- **Chat Systems**: Send debt alerts to team channels
+
+### Automated Reporting
+
+Set up automated debt reporting:
+
+```bash
+#!/bin/bash
+# Daily debt monitoring script
+python scripts/debt_scanner.py . --output daily_scan.json
+python scripts/debt_dashboard.py daily_scan.json --output daily_report.json
+# Send report to stakeholders
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Scanner not finding files**: Check `ignore_patterns` in config
+**Prioritizer giving unexpected results**: Verify business impact scoring
+**Dashboard shows flat trends**: Need more historical data points
+
+### Performance Tips
+
+- Use `.gitignore` patterns to exclude irrelevant files
+- Limit scan depth for large monorepos
+- Run dashboard analysis on subset for faster iteration
+
+### Getting Help
+
+1. Check the `references/` directory for detailed documentation
+2. Review sample data and expected outputs
+3. Examine the tool source code for customization ideas
+
+## Contributing
+
+This skill is designed to be customized for your organization's needs:
+
+1. **Add Detection Rules**: Extend scanner patterns for your tech stack
+2. **Custom Prioritization**: Modify scoring algorithms for your business context
+3. **New Report Formats**: Add output formats for your stakeholders
+4. **Integration Hooks**: Add connectors to your existing tools
+
+The codebase is designed with extensibility in mind - each tool is modular and can be enhanced independently.
+
+---
+
+**Remember**: Technical debt management is a journey, not a destination. These tools help you make informed decisions about balancing new feature development with technical excellence. Start small, measure impact, and iterate based on what works for your team.