Self-Healing Architecture
No project built with StateSpine should ever need 'rebuild from scratch.'
THE PROBLEM
Every project dies the same way.
The "rebuild from scratch" problem doesn't happen overnight. It happens in three stages:
Small shortcuts accumulate. Architecture slowly diverges from intent. "I'll fix this later" × 100. Tests still pass. App still runs.
Every change takes 3x longer than it should. Bug fixes create new bugs. Developers avoid touching certain files. "That module is fragile, don't touch it."
"This codebase is unsalvageable." 6 months of work thrown away. Team morale destroyed. The same cycle begins again.
StateSpine catches Stage 1. Warns at Stage 2. Prevents Stage 3 from ever happening.
THE SOLUTION
Five systems. One purpose.
Self-Healing isn't one feature — it's an interconnected system that makes your project self-aware about its own health, the way a good tech lead notices problems before they become crises.
Architectural Contracts
Define what SHOULD be true. "Components must not import from pages." "No file over 400 lines." StateSpine enforces these rules automatically.
Living Health Manifest
A living document that tracks what IS true right now. Overall health score, contract status, dependencies, tech debt, security — all updated continuously.
Drift Detection
Watches what's CHANGING over time. Alerts when trends go bad, not when it's already too late. "This is the 3rd cross-layer import this week."
Auto-Recovery
From auto-fixes (rename to match conventions) to guided refactoring (split this 500-line file), StateSpine doesn't just warn — it helps you fix.
Prediction Engine
Extrapolates trends to predict the future. "At current rate, tech debt becomes critical in 14 days." Makes the business case for addressing problems now.
SEE IT IN ACTION
Built for how you actually work.
TECHNICAL DETAILS
For power users.
Contract Examples
# .statespine/contracts.yaml
contracts:
- id: "dep-direction-001"
type: dependency_direction
rule: "components/ must NOT import from pages/"
severity: error
- id: "size-001"
type: file_size
rule: "No file exceeds 400 lines"
threshold: 400
severity: warning
- id: "security-001"
type: security
rule: "No secrets in any file outside .env"
severity: critical
auto_fix: trueHealth Score Breakdown
Architecture
25% weight — contract violations, layer boundaries
Dependencies
15% weight — outdated, unused, vulnerable
Code Quality
20% weight — file size, duplication, complexity
Security
20% weight — secrets, validation, vulnerabilities
Tech Debt
15% weight — known issues, estimated remediation
Completeness
5% weight — features defined vs. verified
The Key Insight
Score TRENDS matter more than absolute score. A project at 75 that was 85 last week is MORE concerning than a project stable at 65. StateSpine watches trajectories, not just snapshots.
"At current rate, tech debt will reach critical in ~14 days. Addressing 2 items (est. 5 hours) would stabilize the score."