KyleNesium · KyleNesium · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,5 @@
 .DS_Store
 *.log
-.planning/
 
 # Update mode timestamp file (tracks last passive update check)
 .last-update-check

diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md
@@ -0,0 +1,20 @@
+# Milestones
+
+## v1.0 Linux & WSL2 Cross-Platform Support (Shipped: 2026-04-19)
+
+**Phases completed:** 6 phases, 17 plans  
+**Timeline:** 2026-04-16 → 2026-04-19 (4 days)  
+**Files changed:** 64 files, ~10,950 lines added
+
+**Key accomplishments:**
+
+1. All 5 upkeep skills detect OS/distro at runtime via shared `$OS_TYPE`/`$PKG_MGR` environment detection snippet — macOS-only phases skip gracefully on Linux/WSL2
+2. cleandeep, cleanquick, and audit deliver complete Linux cleanup (apt/dnf/pacman cache, journald vacuum, ~/.cache sweep, Snap & Flatpak orphan removal)
+3. WSL2 environment detected with banner; Windows-side temp and npm/pip cache cleanup offered via `/mnt/c/` bridge
+4. update skill routes to Linux package managers (apt/dnf/pacman/snap/flatpak) with per-tool confirmation gates; Windows pkg managers audited in WSL2 (audit-only, no auto-upgrade)
+5. Umbrella router (`/upkeep`) fully ported — 5 integration gaps (MISS-1 through MISS-5) closed, delivering same Linux/WSL2 experience as dedicated sub-skills
+6. README, badges, and descriptions updated to reflect macOS 14+ / Linux / WSL2 support across all distro families
+
+**Archive:** `.planning/milestones/v1.0-ROADMAP.md`
+
+---
diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md
@@ -0,0 +1,77 @@
+# upkeep
+
+## What This Is
+
+upkeep is a Claude Code skill plugin that does discovery-based system cleanup and package updates. It runs on macOS 14+, Linux (Debian/Ubuntu, Fedora/RHEL, Arch), and WSL2 — routing to the right cleanup phases and package managers based on detected environment.
+
+## Core Value
+
+Every upkeep command gracefully handles macOS, Linux, and WSL2 without errors, skipping unavailable phases rather than failing.
+
+## Requirements
+
+### Validated
+
+- ✓ macOS deep clean (15-phase audit + cleanup) — v1.0.x (pre-milestone)
+- ✓ Quick cleanup (caches + brew) — v1.0.x (pre-milestone)
+- ✓ Audit mode (report only, no changes) — v1.0.x (pre-milestone)
+- ✓ Update skill (git-based skills + package managers) — v1.0.x (pre-milestone)
+- ✓ Discovery-based orphan detection — v1.0.x (pre-milestone)
+- ✓ OS detection utility shared across all skills (macOS / Linux / WSL2) — v1.0
+- ✓ Linux-specific cleanup phases (apt/dnf/pacman cache, journald, ~/.cache, snap, flatpak) — v1.0
+- ✓ All SKILL.md allowed-tools updated with Linux commands — v1.0
+- ✓ WSL2 detection and Windows-side cleanup via /mnt/c/ bridge — v1.0
+- ✓ Linux package manager support in update skill (apt, dnf, pacman, snap, flatpak) — v1.0
+- ✓ README, badges, and SKILL.md descriptions reflect cross-platform support — v1.0
+- ✓ Umbrella router `/upkeep` delivers same Linux/WSL2 experience as dedicated sub-skills — v1.0
+
+### Active
+
+(No active requirements — planning next milestone)
+
+### Out of Scope
+
+- Windows native (CMD/PowerShell) — not a target; WSL2 is the Windows story
+- FreeBSD / other Unix — defer; focus on Linux distros and WSL2
+- GUI / desktop notifications — skill is terminal-only by design
+- Automated (cron) mode — not in scope for this milestone
+- AUR helpers (yay/paru) — deferred to v2
+- AppImage audit/cleanup — deferred to v2
+- Wayland/X11 session cache cleanup — deferred to v2
+- Windows Recycle Bin via WSL2 — deferred to v2
+- WSL2 distro export/import size management — deferred to v2
+
+## Context
+
+upkeep skills are markdown files consumed by Claude Code. The "code" is Claude's instruction set, not shell scripts. OS awareness is implemented as:
+1. OS detection bash snippets at the top of each skill (`$OS_TYPE`, `$OS_DISTRO`, `$PKG_MGR`)
+2. macOS-specific phases wrapped in OS guards (skip gracefully on Linux/WSL2)
+3. Linux-equivalent phase sections added after macOS guards
+4. SKILL.md `allowed-tools` frontmatter updated with Linux commands
+
+**Shipped v1.0:** 5 skill files, 64 files changed, ~10,950 lines across 6 phases.
+
+**Tech stack:** Pure markdown SKILL.md instruction files. No build step, no runtime. Consumed by Claude Code `allowed-tools` frontmatter.
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| OS detection at phase entry, not per-command | Cleaner skill instructions; phases self-skip rather than every command being guarded | ✓ Good — consistent pattern across all 5 skills |
+| Shared OS detection snippet per skill (not a shared file) | Skills are standalone — can't `source` a shared file in Claude Code skill context | ✓ Good — each skill is self-contained |
+| WSL2 treated as Linux + Windows extras | WSL2 runs Linux; build on Linux support then add Windows-side bonus cleanup | ✓ Good — layered cleanly |
+| Linux distro support: Debian/Ubuntu (apt), Fedora/RHEL (dnf), Arch (pacman) | Covers ~90% of Linux desktop users; others get graceful skips | ✓ Good — covers target audience |
+| sudo upgrade surfaced as Manual Steps prose only | Skill never runs sudo; consistency with existing safety rule | ✓ Good — safety preserved |
+| snap/flatpak gated by `command -v`, not `$OS_TYPE` | Handles rare non-Linux installs (Homebrew Linuxbrew, etc.) | ✓ Good — more robust |
+| Umbrella router phases embedded inline (not sub-skill calls) | Claude Code skills are standalone; can't delegate to other skills mid-execution | ✓ Good — no runtime coupling |
+| Gap closure phases 5+6 added after initial audit | Initial 4 phases targeted sub-skills only; umbrella needed separate pass | ✓ Good — audit caught the gap; gap closure closed it |
+
+## Constraints
+
+- **Compatibility**: Must not break existing macOS behavior — all changes are additive guards, not replacements
+- **No sudo**: Skill never runs sudo; applies to Linux too; upgrade commands shown as Manual Steps prose only
+- **Skill format**: Implementation lives in SKILL.md instruction files, not shell scripts
+- **Approval gates**: Any removal operations still require user confirmation (existing pattern)
+
+---
+*Last updated: 2026-04-19 after v1.0 milestone — Linux & WSL2 Cross-Platform Support shipped*
diff --git a/.planning/RETROSPECTIVE.md b/.planning/RETROSPECTIVE.md
@@ -0,0 +1,60 @@
+# Retrospective
+
+## Milestone: v1.0 — Linux & WSL2 Cross-Platform Support
+
+**Shipped:** 2026-04-19  
+**Phases:** 6 | **Plans:** 17 | **Timeline:** 4 days (2026-04-16 → 2026-04-19)
+
+### What Was Built
+
+- OS detection snippet injected into all 5 SKILL.md files — `$OS_TYPE`, `$OS_DISTRO`, `$PKG_MGR` resolved at phase entry
+- Linux cleanup suite (apt/dnf/pacman cache, journald vacuum, ~/.cache sweep, snap/flatpak orphans) in cleandeep, cleanquick, audit
+- WSL2 detection banner + Windows-side cleanup via `/mnt/c/` bridge (Temp, npm cache, pip cache)
+- Linux upgrade paths in update skill (apt/dnf/pacman + snap + flatpak); Windows pkg audit in WSL2 (winget/scoop/choco, audit-only)
+- Full umbrella router parity via gap closure Phases 5+6 — all 5 integration gaps (MISS-1 through MISS-5) closed
+- README, badges, and SKILL.md descriptions updated to reflect macOS 14+ / Linux / WSL2
+
+### What Worked
+
+- **Phase-by-phase verification** caught the umbrella gap early — the v1.0 audit surfaced MISS-1 through MISS-5 before the milestone was declared complete
+- **Additive-only constraint** ("never replace, only guard") kept macOS regressions at zero — every change wrapped in an OS guard
+- **Port-from-sub-skill pattern** for Phases 5+6 was safe and fast — no new logic invented, content verified against known-good source
+- **`command -v` snap/flatpak gating** (not OS_TYPE) correctly handles edge cases like Linuxbrew on macOS without over-specifying
+
+### What Was Inefficient
+
+- **Umbrella gap discovered post-execution**: Phases 1–4 all targeted sub-skills exclusively. The umbrella router (`upkeep/skills/upkeep/SKILL.md`) was self-contained and needed its own pass. Two additional phases (5+6) were required to close the gap — this could have been anticipated in the initial roadmap.
+- **Phase 5 missing VERIFICATION.md**: Phase 5 was executed via direct agent spawn, bypassing the `gsd:execute-phase` workflow which auto-runs `gsd-verifier`. The verification had to be spawned inline during the audit pass.
+- **Summary one_liner field absent**: SUMMARY.md files lacked a `one_liner` frontmatter field, causing `gsd-tools summary-extract` to return null for all files. Accomplishments had to be written manually.
+
+### Patterns Established
+
+- **Umbrella-first rule**: In future multi-file skills, include the umbrella router in every phase plan — not as an afterthought. It doesn't inherit sub-skill changes.
+- **OS guard position**: Guards placed BEFORE `command -v` checks so macOS falls through to existing tool-availability checks unchanged.
+- **sudo as Manual Steps**: Upgrade commands that require sudo appear only in prose blockquote/Manual Steps sections, never in executable bash fences.
+- **WSL2 `/mnt/c` outer guard**: All Windows-side operations wrapped in `if [ -d "/mnt/c" ]` outer guard to prevent path stat errors surfacing to users.
+
+### Key Lessons
+
+- **Umbrella routers need their own execution plan** — they don't inherit from sub-skills
+- **Phase verifications should always go through execute-phase workflow** to ensure VERIFICATION.md is auto-created
+- **Add `one_liner` to SUMMARY.md template** so gsd-tools can extract accomplishments automatically
+- **Audit before complete** paid off — caught a high-severity gap (MISS-2, MISS-5) that would have shipped broken Linux support
+
+### Cost Observations
+
+- Sessions: Multiple (context-compacted mid-milestone)
+- Notable: Phase 6 had 87 edit operations in one plan (the umbrella Update Mode is large); still completed in one agent execution
+
+---
+
+## Cross-Milestone Trends
+
+| Metric | v1.0 |
+|--------|------|
+| Phases | 6 |
+| Plans | 17 |
+| Timeline | 4 days |
+| Audit gaps found | 5 |
+| Audit gaps closed | 5 |
+| Regression count | 0 |
diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
@@ -0,0 +1,32 @@
+# Roadmap: upkeep
+
+## Milestones
+
+- ✅ **v1.0 Linux & WSL2 Cross-Platform Support** — Phases 1–6 (shipped 2026-04-19)
+
+## Phases
+
+<details>
+<summary>✅ v1.0 Linux & WSL2 Cross-Platform Support (Phases 1–6) — SHIPPED 2026-04-19</summary>
+
+- [x] Phase 1: OS Detection & Config (5/5 plans) — completed 2026-04-17
+- [x] Phase 2: Linux Cleanup (5/5 plans) — completed 2026-04-17
+- [x] Phase 3: WSL2 Support (3/3 plans) — completed 2026-04-17
+- [x] Phase 4: Update Skill & Polish (2/2 plans) — completed 2026-04-17
+- [x] Phase 5: Umbrella Router — Linux Cleanup Phase Parity (1/1 plan) — completed 2026-04-18
+- [x] Phase 6: Umbrella Router — Update Mode Linux Parity (1/1 plan) — completed 2026-04-19
+
+Full details: `.planning/milestones/v1.0-ROADMAP.md`
+
+</details>
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. OS Detection & Config | v1.0 | 5/5 | Complete | 2026-04-17 |
+| 2. Linux Cleanup | v1.0 | 5/5 | Complete | 2026-04-17 |
+| 3. WSL2 Support | v1.0 | 3/3 | Complete | 2026-04-17 |
+| 4. Update Skill & Polish | v1.0 | 2/2 | Complete | 2026-04-17 |
+| 5. Umbrella Router — Linux Cleanup Phase Parity | v1.0 | 1/1 | Complete | 2026-04-18 |
+| 6. Umbrella Router — Update Mode Linux Parity | v1.0 | 1/1 | Complete | 2026-04-19 |
diff --git a/.planning/STATE.md b/.planning/STATE.md
@@ -0,0 +1,46 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: Linux & WSL2 Cross-Platform Support
+status: complete
+stopped_at: Milestone v1.0 complete — shipped 2026-04-19
+last_updated: "2026-04-19T00:00:00.000Z"
+progress:
+  total_phases: 6
+  completed_phases: 6
+  total_plans: 17
+  completed_plans: 17
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-04-19)
+
+**Core value:** Every upkeep command gracefully handles macOS, Linux, and WSL2 without errors
+**Current focus:** v1.0 shipped — planning next milestone
+
+## Current Position
+
+Milestone v1.0 complete. All 6 phases, 17 plans shipped and verified.
+
+## Accumulated Context
+
+### Key Decisions
+
+Logged in PROJECT.md Key Decisions table.
+
+### Pending Todos
+
+None.
+
+### Blockers/Concerns
+
+None.
+
+## Session Continuity
+
+Last session: 2026-04-19
+Stopped at: Milestone v1.0 complete
+Resume file: None
diff --git a/.planning/config.json b/.planning/config.json
@@ -0,0 +1,15 @@
+{
+  "mode": "yolo",
+  "granularity": "coarse",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": false,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": false,
+    "auto_advance": false,
+    "_auto_chain_active": false
+  }
+}
diff --git a/.planning/milestones/v1.0-MILESTONE-AUDIT.md b/.planning/milestones/v1.0-MILESTONE-AUDIT.md
@@ -0,0 +1,123 @@
+---
+milestone: v1.0 — Linux & WSL2 Cross-Platform Support
+audited: 2026-04-19
+phases: 6
+requirements_total: 23
+requirements_satisfied: 23
+integration_gaps: 0
+minor_findings: 4
+tech_debt_items: 2
+verdict: passed
+---
+
+# Milestone Audit: v1.0 — Linux & WSL2 Cross-Platform Support
+
+**Audited:** 2026-04-19 (re-audit after gap closure)
+**Phases audited:** 6 of 6 (all complete, all phase verifications passed)
+**Requirements:** 23/23 satisfied
+**Verdict:** `passed` — all requirements satisfied; umbrella router fully updated; no blocking gaps
+
+---
+
+## 1. Requirements Coverage
+
+All 23 v1 requirements satisfied across all 6 phases:
+
+| Phase | Requirements | Status |
+|-------|-------------|--------|
+| Phase 1: OS Detection & Config | OS-01, OS-02, OS-03, OS-04, CFG-01 | ✓ All satisfied |
+| Phase 2: Linux Cleanup | LNX-01–08 | ✓ All satisfied |
+| Phase 3: WSL2 Support | WSL-01–04 | ✓ All satisfied |
+| Phase 4: Update Skill & Polish | UPD-01–04, CFG-02, CFG-03 | ✓ All satisfied |
+| Phase 5: Umbrella Cleanup Parity | OS-01, LNX-01, LNX-02, LNX-04, LNX-05, LNX-06, WSL-02, WSL-03 | ✓ All satisfied (umbrella) |
+| Phase 6: Umbrella Update Parity | UPD-01, UPD-02, UPD-03, WSL-04 | ✓ All satisfied (umbrella) |
+
+**Coverage: 23/23 — no unmapped requirements.**
+
+---
+
+## 2. Phase Verification Summary
+
+| Phase | Score | Status | Notes |
+|-------|-------|--------|-------|
+| 01-os-detection-config | All must-haves | passed | |
+| 02-linux-cleanup | All must-haves | passed | |
+| 03-wsl2-support | All must-haves | passed | |
+| 04-update-skill-polish | 6/6 | passed | UPD-04 gap closed inline |
+| 05-umbrella-cleanup-parity | 8/8 | passed | Phase 1/2/9/16/17/18 all wired |
+| 06-umbrella-update-parity | 7/7 | passed | Step 2/3/5/6 all wired |
+
+---
+
+## 3. Integration Check
+
+**Result: `passed`** — All 23 requirements are wired end-to-end through the umbrella router.
+
+### E2E Flows Verified
+
+| Flow | Entry Point | Status |
+|------|-------------|--------|
+| Ubuntu deep clean (`/upkeep deep`) | `upkeep/skills/upkeep/SKILL.md` | PASS — Phase 1 Linux baseline → Phase 2 apt cache → Phase 9 journalctl → Phase 16 snap/flatpak all present |
+| Linux system update (`/upkeep update`) | `upkeep/skills/upkeep/SKILL.md` | PASS — Step 5 $PKG_MGR dispatch (apt/dnf/pacman) + snap refresh + flatpak update all wired |
+| WSL2 deep clean (`/upkeep deep` in WSL2) | `upkeep/skills/upkeep/SKILL.md` | PASS — Phase 17 Windows Temp + Phase 18 Windows npm/pip present; Step 2 WSL2 pkg detection wired |
+
+### Minor Findings (Non-blocking, LOW/NEGLIGIBLE severity)
+
+| ID | Severity | Location | Description |
+|----|----------|----------|-------------|
+| F-01 | LOW | `cleanquick/SKILL.md` Phase 1 | Linux baseline info (df, os-release, uname) not included in quick mode — Phase 1 goes straight to cleanup without environment banner equivalent on Linux |
+| F-02 | LOW | `audit/SKILL.md` reporting table | Snap row absent from the audit summary table footer (snap content is present in the phase body) |
+| F-03 | LOW | `upkeep/skills/upkeep/SKILL.md` Phase 3 | Umbrella ~/.cache approval gate differs slightly from cleandeep sub-skill phrasing (functional parity achieved, wording variance only) |
+| F-04 | NEGLIGIBLE | Multiple sub-skill SKILL.md descriptions | `cleandeep`, `cleanquick`, `audit`, `update` sub-skill descriptions still say "macOS" in the one-liner; CFG-02 satisfied at umbrella level |
+
+None of these findings block any primary Linux or WSL2 user path. All are candidates for v1.1 polish.
+
+---
+
+## 4. Gap Closure Summary (vs. v1.0 Initial Audit)
+
+The initial audit (`audited: 2026-04-17`) found 5 integration gaps in the umbrella router. All are now closed:
+
+| Gap | Severity | Phase Closed | Status |
+|-----|----------|-------------|--------|
+| MISS-1: Phase 1 Baseline — no Linux branch for sw_vers | Low | Phase 5 | ✓ Closed |
+| MISS-2: Phase 2 Homebrew Audit — Linux skips with no substitute | High | Phase 5 | ✓ Closed |
+| MISS-3: Phase 9 Stale Logs — no journalctl block | Medium | Phase 5 | ✓ Closed |
+| MISS-4: Phases 16–18 absent | Medium | Phase 5 | ✓ Closed |
+| MISS-5: Update Mode Step 5 — missing Linux upgrade paths + WSL2 pkg detection | High | Phase 6 | ✓ Closed |
+
+---
+
+## 5. Tech Debt (Non-blocking)
+
+| ID | File | Location | Description | Impact |
+|----|------|----------|-------------|--------|
+| TD-01 | `README.md` | Lines 46–50 | "Why upkeep?" section describes only macOS pain points; cross-platform angle absent | Cosmetic — all other README sections are cross-platform |
+| TD-02 | `README.md` | Lines 268, 272 | Privacy section references "standard macOS locations" and "standard macOS commands" | Accurate for macOS scope but phrasing slightly stale |
+
+---
+
+## 6. Deferred Work (v2)
+
+| ID | Description | Phase Deferred In |
+|----|-------------|-------------------|
+| LNX-V2-01 | AUR helper updates (yay/paru) in update skill | Phase 4 |
+| LNX-V2-02 | AppImage audit and cleanup | Phase 2 |
+| LNX-V2-03 | Wayland/X11 session cache cleanup | Phase 2 |
+| WSL-V2-01 | Windows Recycle Bin audit via WSL2 bridge | Phase 3 |
+| WSL-V2-02 | WSL2 distro export/import size management | Phase 3 |
+
+---
+
+## 7. Verdict
+
+**`passed`** — All 23 v1 requirements are satisfied in both the dedicated sub-skills and the umbrella router. The five integration gaps identified in the initial audit have been closed across Phases 5 and 6. Users invoking `/upkeep deep`, `/upkeep quick`, `/upkeep audit`, or `/upkeep update` on Linux or WSL2 receive the full cross-platform experience.
+
+The 4 minor findings (F-01 through F-04) and 2 tech debt items do not block the v1.0 release — they are candidates for v1.1 polish.
+
+---
+
+*Initial audit: 2026-04-17 (verdict: gaps_found — 5 integration gaps)*
+*Re-audit: 2026-04-19 (verdict: passed — all gaps closed)*
+*Audited by: gsd-integration-checker + gsd-verifier + orchestrator*
+*Source: 6x VERIFICATION.md (all passed) + REQUIREMENTS.md traceability (23/23 Complete) + integration check of upkeep/skills/upkeep/SKILL.md*