Nightly Maintenance Architecture

Status: Partially implemented (4/9 active, 5 planned) Kanban task: simplify-nightly-kanban-actions Demo visualization: /nightly-maintenance in demo app

Overview

The nightly maintenance pipeline is a set of focused, single-purpose jobs that run sequentially after hours (UTC). Each job answers one question about the codebase, makes one type of change, and produces output reviewable in under a minute.

Goal: Automate the work that would otherwise require dedicated engineers — code review, documentation, dependency management, tech debt reduction — without adding headcount.

Pipeline Timeline

UTC   Job                        Status      Slack Channel
────  ─────────────────────────  ──────────  ──────────────
00:00 ① Daily Overview           ✅ ACTIVE    #daily-overview
02:00 ② Dead Code Cleanup        ✅ ACTIVE    #ai-janitor
03:00 ③ New Code Reviewer        🔲 PLANNED   #ai-janitor
04:00 ④ Boy Scout Scanner        🔲 PLANNED   #ai-janitor
05:00 ⑤ Documentation Generator  🔲 PLANNED   #ai-janitor
06:00 ⑥ Dependency Health        ✅ ACTIVE    #ai-janitor
07:00 ⑦ Kanban Hygiene           ✅ ACTIVE    #ai-janitor
08:00 ⑧ Performance Baseline     🔲 PLANNED   #ai-janitor
05:00 ⑨ Architecture Review      ✅ ACTIVE    #ai-janitor

Jobs run 2 hours apart to avoid CI resource contention and allow later jobs to consume earlier outputs.

Universal Job Pattern

Every nightly job follows the same 3-step architecture:

┌─────────────────────────────────────────────────────┐
│                   GitHub Actions                     │
│                                                      │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────┐ │
│  │  Step 1       │   │  Step 2       │   │  Step 3   │ │
│  │  PRE-SCAN     │──▶│  LLM REVIEW   │──▶│  APPLY    │ │
│  │              │   │              │   │          │ │
│  │ Deterministic │   │ Claude (if    │   │ Create PR │ │
│  │ TypeScript    │   │ candidates    │   │ Post Slack│ │
│  │ Zero LLM cost│   │ exist)        │   │ Update    │ │
│  │              │   │              │   │ memory    │ │
│  └──────────────┘   └──────────────┘   └──────────┘ │
│        │                   │                  │      │
│        ▼                   ▼                  ▼      │
│   candidates.json    decisions.json    PR + Slack    │
└─────────────────────────────────────────────────────┘

Why this pattern?

1. Zero cost when clean — Pre-scan gates the LLM. No candidates = no Claude API call.
2. Testable — Deterministic steps can be unit tested without LLM mocking.
3. Reviewable — Each step produces a JSON artifact that's inspectable.
4. Bounded cost — LLM step has explicit --max-turns cap.

Job Details

① Daily Overview (00:00 UTC) — ✅ ACTIVE

Data flow:

gh pr list (merged) ──▶ Claude ──▶ daily-overview.md ──▶ PR ──▶ Slack
gh log (commits)    ──┘

② Dead Code Cleanup (02:00 UTC) — ✅ ACTIVE

Rotation: 35 workspaces, one per night. Full rotation = ~5 weeks.

Data flow:

rotation.json ──▶ Knip scan ──▶ findings?
                                  │
                    ┌─────────────┼─────────────┐
                    ▼             ▼              ▼
                 0 findings    N findings     Invalid JSON
                    │             │              │
                    ▼             ▼              ▼
               Update tracker  Claude review   Warn + skip
               Clean PR        Remove code
               Auto-merge      Verify (lint+tc)
                               PR + Slack

③ New Code Reviewer (03:00 UTC) — 🔲 PLANNED

Candidate categories:

• Security (OWASP top 10, injection, XSS)
• Error handling (missing try/catch, swallowed errors)
• Race conditions (async patterns, state management)
• Edge cases (null checks, boundary conditions)
• Performance (N+1 queries, unnecessary re-renders, large bundles)
• Pattern violations (direct process.env, import-time env access)

④ Boy Scout Scanner (04:00 UTC) — 🔲 PLANNED

Examples of inline fixes:

• Replace raw console.error with useSentryToast
• Add missing lazy initialization pattern
• Extract 20-line inline function to named function
• Remove unused imports

Examples of kanban tasks created:

• "Refactor 1500-line VideoRespondentDashboard into sub-components"
• "Extract duplicate Sentry registration to shared utility" (already done as boyscout task)

⑤ Documentation Generator (05:00 UTC) — 🔲 PLANNED

Content categories:

• Feature explanation pages (what it does, how to use it)
• FAQ entries (common questions from support/usage patterns)
• API endpoint documentation (request/response schemas)
• Integration guides (webhooks, embed codes)
• Changelog entries (human-readable release notes)

⑥ Dependency Health (06:00 UTC) — 🔲 PLANNED

Auto-merge criteria (no LLM needed):

• Patch version bumps (1.2.3 → 1.2.4)
• Known-safe minor bumps (types packages, linters)

LLM review needed:

• Major version bumps (breaking changes)
• Minor bumps with large changelogs
• New transitive dependencies

⑦ Kanban Hygiene (07:00 UTC) — ✅ ACTIVE

Focused on 4 checks (simplified from original 12 responsibilities):

1. Status sync (task status matches merged PR state)
2. Staleness detection (>60 days without activity in Backlog)
3. Duplicate flagging (shared impactedApps + overlapping title keywords)
4. Archive Done tasks (move to .kanbn/archived-tasks/)

⑧ Performance Baseline (08:00 UTC) — 🔲 PLANNED

Metrics tracked:

• Bundle size per app (JS + CSS)
• Build time per app
• Number of dependencies per app
• Optional: Core Web Vitals from Lighthouse

⑨ Architecture Review (05:00 UTC) — ✅ ACTIVE

Rotation: 22 targets (11 apps + 11 packages), one per night. Full rotation ≈ 3 weeks.

Human decisions captured as kanban tasks — when the review identifies an improvement that requires judgment (e.g. "should we extract this to a shared package?"), a kanban task is created with a ## Human Decision Needed section. The reviewer answers in a follow-up session.

Data flow:

rotation.json ──▶ collect candidates ──▶ Claude reviews docs vs code
                                              │
                              ┌────────────────┼───────────────┐
                              ▼                ▼               ▼
                        Update outdated   Create new     Create improvement
                        docs + Mermaid    docs           kanban tasks with
                        diagrams                         human questions
                              │                │               │
                              └────────┬───────┘               │
                                       ▼                       ▼
                                   PR (needs review)    Tasks in .kanbn/tasks/
                                   Slack #ai-janitor    (human answers later)

Future Ideas (Backlog)

Memory & State

Nightly jobs persist state in .kanbn/memory/:

Implementation Priority

File Index

.github/
├── workflows/
│   ├── daily-overview.yml              ① trigger
│   ├── daily-overview-post.yml         ① Slack relay
│   ├── nightly-dead-code-cleanup.yml   ② trigger
│   ├── nightly-product-verification.yml ⑦ legacy (disabled)
│   └── nightly-kanban-hygiene.yml      ⑦ trigger (active)
├── prompts/
│   ├── daily-overview.md               ① prompt
│   ├── nightly-dead-code-cleanup.md    ② prompt
│   ├── nightly-pv-review.md            ⑦ legacy prompt
│   ├── nightly-kanban-hygiene.md       ⑦ prompt (Step 2)
│   └── nightly-architecture-review.md  ⑨ prompt

packages/ci-scripts/src/
├── get-daily-overview-window.ts              ① helper
├── find-daily-overview-file.ts               ① helper
├── post-daily-overview-to-slack.ts           ① Slack
├── post-dead-code-cleanup-to-slack.ts        ② Slack
├── nightly-pv-collect.ts                     ⑦ Step 1
├── nightly-pv-apply.ts                       ⑦ Step 3
├── post-product-verification-to-slack.ts     ⑦ Slack
├── nightly-architecture-review-collect.ts    ⑨ Step 1
└── post-architecture-review-to-slack.ts      ⑨ Slack

.kanbn/memory/
├── dead-code-rotation.json            ② state
├── board-health.json                  ⑦ state
├── performance-baselines.json         ⑧ state (planned)
└── architecture-review-rotation.json  ⑨ state

.claude/skills/architecture-review/
├── SKILL.md                           ⑨ on-demand companion skill
└── references/
    ├── coverage-map.md                ⑨ doc coverage tracking
    └── review-checklist.md            ⑨ verification checklist

docs/architecture/
└── nightly-maintenance-architecture.md  This document