maintenance

Maintenance

A config-driven, cross-platform maintenance system that periodically verifies code quality, document correctness, and SKILL documentation AI-friendliness. The orchestrator reads bin/maintenance/config.psd1, runs check scripts on a schedule, persists results to shared state, and reports through multiple formatters (console, JSON, markdown, GitHub annotations).

When to Use

• "run maintenance"
• "run CI checks" / "run nightly checks"
• "check code quality"
• "verify SKILL frontmatter"
• "audit documentation links"
• "check for dead code"
• "run coverage check"
• "clean up build artifacts"
• "add a new maintenance check"
• "force-run all maintenance tasks"
• "check the maintenance state"

How It Works

The orchestrator (bin/maintenance/orchestrator.ps1) is the central entry point. It reads task definitions from config.psd1, checks the shared state file to avoid redundant re-runs (unless -Force), executes each task with the configured interval, collects result objects, and routes them through reporters.

Result object contract — every check script emits a PSCustomObject:

@{
    CheckId    = "A1"
    Name       = "Compilation Check"
    Status     = "passed"  # passed | failed | skipped | error
    DurationMs = 1234
    ExitCode   = 0
    Details    = "Maven + Cargo compile OK"
    Results    = @( @{ Item="..."; Status="passed"; Message="..." } )
    Artifacts  = @( "bin/maintenance/logs/A1-20260714.json" )
    Timestamp  = "2026-07-14T14:30:22Z"
}

Usage

All commands are run from the repository root.

Orchestrator (primary entry point)

# One pass (run pending tasks, skip if still within interval)
pwsh bin/maintenance/orchestrator.ps1 -Once

# Continuous loop (dev mode — warn only, never fails)
pwsh bin/maintenance/orchestrator.ps1

# Force all tasks regardless of last-run state
pwsh bin/maintenance/orchestrator.ps1 -Force -Once

# CI mode (strict — first failure exits 1)
MAINTENANCE_MODE=ci pwsh bin/maintenance/orchestrator.ps1 -Once

# Nightly mode (collects all failures, reports at end)
MAINTENANCE_MODE=nightly pwsh bin/maintenance/orchestrator.ps1 -Once