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

CI entry points

# Per-commit safety checks (fast)
pwsh bin/maintenance/ci/invoke-ci-checks.ps1

# Full nightly suite (thorough)
pwsh bin/maintenance/ci/invoke-nightly-checks.ps1

Running individual checks

# Syntax-check all PS1 scripts
pwsh bin/maintenance/checks/check-ps1-syntax.ps1

# Validate SKILL.md YAML frontmatter
pwsh bin/maintenance/checks/check-skill-frontmatter.ps1

# Validate internal doc links
pwsh bin/maintenance/checks/check-doc-links-internal.ps1

# Check version consistency across files
pwsh bin/maintenance/checks/check-version-consistency.ps1

# Run code coverage check
pwsh bin/maintenance/checks/check-coverage.ps1

# Detect dead code
pwsh bin/maintenance/checks/check-dead-code.ps1

# Clean stale build artifacts (dry-run first)
pwsh bin/maintenance/checks/clean-build-artifacts.ps1

Execution Modes

Check Categories

Complete Check Inventory

Additional on-demand checks not in the default config: check-changelog-staleness.ps1, check-ci-workflows.ps1, check-e2e-tests.ps1, check-integration-tests.ps1, check-qodana.ps1, check-readme-staleness.ps1, check-release-assets.ps1.

Shared State

The orchestrator persists run history to bin/maintenance/state/maintenance-state.json, which is tracked in git so the whole team shares one view.

How skip logic works: A task is skipped if it ran within its configured IntervalSeconds. This means CI nightly running check-coverage prevents a developer's orchestrator from re-running it within 24 hours. Force mode (-Force) or CI mode bypass this entirely.

File locking prevents corruption when two processes write simultaneously. Stale locks (older than 60 seconds) are automatically broken.

Thresholds

All numeric thresholds live in bin/maintenance/thresholds/thresholds.psd1. Override any value via environment variable:

MAINTENANCE_Coverage_Global=0.75 pwsh bin/maintenance/orchestrator.ps1 -Once
MAINTENANCE_LogHealth_MaxTotalMB=200 pwsh bin/maintenance/orchestrator.ps1 -Once

Adding a New Check

1. Create bin/maintenance/checks/check-my-thing.ps1 following the result object contract
2. Add a task entry to bin/maintenance/config.psd1 with Name, Description, Enabled, IntervalSeconds, ScriptPath
3. If it's a CI-level check, add it to bin/maintenance/ci/invoke-ci-checks.ps1
4. If it's a nightly check, add it to bin/maintenance/ci/invoke-nightly-checks.ps1

Reporters

Directory Layout

bin/maintenance/
├── config.psd1              # Task definitions and intervals
├── orchestrator.ps1         # Master scheduler
├── common/
│   ├── MaintenanceUtil.ps1  # Logging, results, threshold helpers
│   └── MaintenanceState.ps1 # State I/O with file locking
├── checks/                  # 30 check/clean scripts
├── reporters/               # Output formatters
├── ci/                      # CI entry points
├── state/
│   └── maintenance-state.json  # Shared run history (git-tracked)
└── thresholds/
    └── thresholds.psd1      # Numeric thresholds

Dependencies

• PowerShell Core 6+ (pwsh)
• Git (repository root resolution)
• Maven Wrapper (mvnw / mvnw.cmd)
• Cargo (Rust CLI checks)
• Docker (Qodana, integration tests, Dockerfile checks)
• Python 3 (bin/quality/fix-links.py)
• ripgrep (rg) recommended for fast content search