feat(scripts): maintain.ps1 — daily heartbeat with smart notifications

[abdout]

Summary

Implements spec #27. The daily heartbeat that composes the existing scripts into one autonomous run and surfaces problems through the right notification channel.

maintain -Install              # one-time setup
maintain -Status               # what's armed, when next, last result
maintain -Run                  # force run now (default)
maintain -Uninstall            # remove scheduled task

Builds on #29 (doctor.ps1) — maintain is doctor's consumer.

What's in the PR

• ~/.claude/scripts/maintain.ps1 (208 lines) — main entry point
• ~/.claude/scripts/lib/Notify.ps1 (60 lines) — Send-Toast (BurntToast), Send-Slack (webhook), Get-EnvVar (.env reader)

Flow

sync-repos.ps1  →  git pull ~/kun  →  doctor.ps1  →  notify  →  log
   ~10s             ~5s (diff-gated)    ~3s         <1s        <1s

Total ~20s on a healthy machine. Doesn't block user work.

Notification matrix (from spec #27)

doctor exit	Toast	Slack	GitHub	Console (if -Run)
0 (green)	—	—	Weekly (Mon only)	Brief OK
2 (warnings)	⚠️	—	—	Full table
3 (updates)	🔄 with "Run doctor -Update" button	—	—	Update list
1/4 (errors)	❌	Yes via SLACK_WEBHOOK_URL	Same comment as -Report	Full table

Silent on green is deliberate — notification fatigue kills daily tasks.

Self-update logic

git pull --rebase ~/kun
# Only re-run install.ps1 if .claude/ files actually changed
if (git diff before..after | grep '^.claude/') { install.ps1 }

Diff-gated. Saves cycles when there's no config change.

Log handling

Per-day file at ~/.claude/logs/maintain-<YYYY-MM-DD>.log. Rotated automatically — files older than 30 days are deleted at the start of each run.

[2026-05-16T17:19:54Z] [INFO] start (HOSTNAME)
[2026-05-16T17:19:54Z] [OK]   sync-repos: ok
[2026-05-16T17:19:54Z] [OK]   self-update: no changes on ~/kun
[2026-05-16T17:19:54Z] [INFO] doctor: exit 3
[2026-05-16T17:19:54Z] [OK]   notify: toast (update available)
[2026-05-16T17:19:54Z] [INFO] end (duration 19s)

Scheduled task

maintain -Install creates a daily Windows task armed at 09:00 local (override via -Schedule HH:mm). Uses /RL HIGHEST so it can refresh certificate stores and run elevated cmdlets. Idempotent (/F replaces in place; re-running doesn't duplicate).

If the user isn't running as Administrator, install fails gracefully and prints the manual schtasks command.

Test plan

• maintain -Install creates task kun-maintain (verify with Get-ScheduledTask)
• Re-running -Install doesn't duplicate the task
• maintain -Status shows next run, last result, log path
• maintain -Uninstall removes the task; idempotent
• maintain -Run -DryRun exercises full flow without side effects — verified ✅
• Forced run via Start-ScheduledTask kun-maintain fires real notifications
• Logs rotate after 30 days (synthetic test: seed old files, run, verify deletion)
• Self-update only triggers install.ps1 when .claude/ files change in the pulled commits
• BurntToast install failure falls back gracefully (verified: Send-Toast returns $false, logs continue)
• SLACK_WEBHOOK_URL not in .env → Slack channel silently skipped
• All PowerShell files parse without errors — verified ✅

Open items not blocking this PR

• macOS/Linux equivalents are follow-up work
• A Pester suite for the pure helpers (log path generation, semver compare, Slack JSON) is nice-to-have, not blocking

Dependencies

This branch stacks on feat/doctor (PR #29). Once #29 merges to main, rebase this onto main and it lands cleanly.

Closes #27

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kun	Ready	Preview, Comment	May 16, 2026 3:21pm