mattjaikaran /meridian:health — DB and Artifact Health Check
Validate SQLite database integrity, artifact consistency, and detect stuck phases.
Optional --repair flag auto-advances stale states and prunes orphaned rows.
Arguments
- (no args) — run all checks, report findings
--repair— auto-repair repairable issues (stale states, orphaned rows)--stuck-hours N— override stuck phase threshold (default: 4 hours)
Keywords
health, integrity, check, stuck, orphan, repair, artifacts, consistency, validate, preflight
Procedure
Run health check (read-only)
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from pathlib import Path
from scripts.health import run_health_check
result = run_health_check(Path('.'), do_repair=False)
print(json.dumps(result, indent=2))
"
Run with --repair
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from pathlib import Path
from scripts.health import run_health_check
result = run_health_check(Path('.'), do_repair=True)
print(json.dumps(result, indent=2))
"
Run with custom stuck threshold (e.g. 8 hours)
PYTHONPATH=$MERIDIAN_HOME uv run --project $MERIDIAN_HOME -- python -c "
import json
from pathlib import Path
from scripts.health import run_health_check
result = run_health_check(Path('.'), do_repair=False, stuck_threshold_hours=8)
print(json.dumps(result, indent=2))
"
Display Format
After running, present findings grouped by check type:
## Meridian Health Check
Status: ok | warning | error
### DB Integrity
[ok] integrity_check — passed
[ok] schema_version — v8
### Orphaned Rows
[warn] Plan id=12 references non-existent phase_id=99
### Artifact Consistency
[warn] Phase 'Add auth' (id=3, executing) has no artifact dir
### Stuck Phases
[warn] Phase 'Deploy' (id=5) executing for 6.2h (threshold: 4h)
### Repair Log (only shown when --repair used)
- Reverted stuck phase id=5 to 'planned_out'
- Deleted orphaned plan id=12
Icons: ok → ✓ warning → ⚠ error → ✗
If status == "ok" and no repair log: print a single success line.
If status == "no_db": tell the user to run /meridian:init.
What Each Check Does
| Check | What it validates |
|---|---|
integrity_check |
SQLite page-level corruption via PRAGMA integrity_check |
foreign_key_check |
FK constraint violations via PRAGMA foreign_key_check |
schema_version |
DB schema version matches code expectation |
orphaned_rows |
Plans with no phase, phases with no milestone |
artifact_consistency |
.planning/phases/ dirs vs DB phase records |
stuck_phases |
Phases in executing for longer than threshold |
Repair Actions
| Finding | Repair |
|---|---|
| Orphaned plan | Delete plan row |
| Orphaned phase | Delete phase and its plans |
| Stuck phase | Revert to planned_out, clear started_at |
--repair is non-destructive for completed work — it only touches rows with no valid parent or phases that have been stuck with no heartbeat.
Pre-flight in /meridian:resume
/meridian:resume runs a silent health check before generating the resume prompt.
If warnings or errors are found, they are surfaced before the resume output.
Pass --skip-health to bypass the pre-flight check.