/system-cleanup

name: system-cleanup
description: "The world feels messy. Stale tasks, orphan folders, v2 remnants, unsaved sessions — entropy is accumulating and needs to be addressed before it compounds. Scans across all walnuts, then surfaces issues one at a time."
user-invocable: true

Tidy

System maintenance. Root health first, then one walnut at a time. Surfaces issues with recommended fixes — the human picks.

Not a dashboard (that's world). Not a search (that's find). Not session history (that's alive:session-history). Pure maintenance.

---

v3 Architecture Reference

Walnut structure is flat under `_kernel/`:

walnut-name/
  _kernel/
    key.md
    log.md
    insights.md
    tasks.json
    now.json
    completed.json
  bundle-a/
    context.manifest.yaml
    raw/
  bundle-b/
    context.manifest.yaml

There is NO `_kernel/_generated/` subdirectory. There is NO `bundles/` container directory. Bundles sit as direct children of the walnut root alongside `_kernel/`.

Task operations go through `tasks.py`, never by reading/writing task files directly:

• `tasks.py list --walnut {path}` — all active tasks as JSON
• `tasks.py list --walnut {path} --status active` — filter by status
• `tasks.py summary --walnut {path}` — structured summary with counts

Projection rebuilds go through `project.py`:

• `project.py --walnut {path}` — rebuilds `_kernel/now.json`

---

Three-Phase Flow

Phase 1: Root Audit (system-level, 7 checks — parallel subagents)
    |
Phase 2: Walnut Summary (single subagent scans frontmatter, human picks)
    |
Phase 3: Deep Audit (one walnut, 12 checks — parallel subagents)

---

Subagent Strategy (non-negotiable)

Tidy is read-heavy. Every phase uses subagents to keep the main context clean.

**Discovery subagents MUST use `subagent_type: "Explore"`** — Explore agents have direct file read access without needing Bash. Use Explore for all Phase 1, Phase 2, and Phase 3 discovery checks.

**Fix-execution subagents MUST use `subagent_type: "general-purpose"`** — only general-purpose agents have Write/Edit access. Dispatch one general-purpose agent per approved fix.

• **Phase 1:** Dispatch all 7 root checks as parallel subagents. Wait for all. Present results together — one line per passing check, expand on failures only.
• **Phase 2:** Single subagent reads all walnut frontmatter, returns the health table.
• **Phase 3:** Dispatch all 12 checks as parallel subagents (one check per subagent). Wait for all. Present results together — passing checks collapsed, failures expanded one at a time.

Each subagent gets: the subagent brief (read `$ALIVE_PLUGIN_ROOT/templates/subagent-brief.md` once, prepend to every agent prompt), the check description, what to scan, what constitutes a pass/fail, and instructions to return a structured result (pass/fail + details if fail). **Without the brief, subagents will not understand walnut/bundle structure, tasks.py, or v3 conventions.**

**Never read walnut files in the main context.** All file reading happens inside subagents. The main context only sees results.

---

Presentation Rules

• **Passing checks:** Collapse to one line. `✓ 3a. now.json zero-context — pass`. No details.
• **Failing checks:** Expand with quote block, recommended fix, and options. One at a time.
• **After presenting all results:** Walk through failures one at a time for the human to resolve or skip.

---

Phase 1 — Root Audit

Dispatch 7 subagents in parallel. Each checks one thing across the whole world.

1a. ALIVE Structure

Verify all 5 ALIVE folders exist at the world root (`01_Archive/` through `05_Experiments/`).

Pass: all 5 exist. Fail: any missing.

1b. Inputs Buffer

Scan `03_Inbox/` for items older than 48 hours. Unrouted inputs may contain decisions or context affecting active walnuts.

Pass: empty or nothing older than 48h. Fail: items found.

> **🐿️ tidy — unrouted inputs**
> 03_Inbox/ has 3 items older than 48 hours:
>  - vendor-brochure.pdf (3 days)
>  - meeting-notes-feb20.md (4 days)
>
> ▸ route via alive:capture-context / skip

1c. Cross-Walnut Links

Scan ALL walnuts' `_kernel/key.md` frontmatter (`links:` and `parent:` fields) AND body text for `[[wikilinks]]`. Check for:

• **Broken wikilinks** — links pointing to walnut names that don't exist as folders
• **Orphan parents** — `parent:` pointing to a non-existent walnut
• **Undeclared connections** — `[[wikilinks]]` used in body text or log entries but NOT in the frontmatter `links:` field. These are invisible to `alive:search-world` traversal.
• **Structureless folders** — folders in ALIVE domains (02-05) that have no `_kernel/` but look like they should be walnuts

1d. Walnut Structural Integrity

Quick scan that every walnut has the full v3 flat `_kernel/` skeleton:

• 3 narrative files: `_kernel/key.md`, `_kernel/log.md`, `_kernel/insights.md`
• 2 data files: `_kernel/tasks.json`, `_kernel/now.json`
• 1 archive file: `_kernel/completed.json`

There is NO `_kernel/_generated/` subdirectory expected. There is NO `bundles/` container directory expected. If either is found, that is a separate check (see 1d does not flag these — checks 3k and 3l handle v2 remnant detection during deep audit).

Pass: all walnuts have all 6 files in flat `_kernel/`. Fail: list what's missing where.

1e. Unsaved Squirrel Entries

Scan `.alive/_squirrels/` (world-level) for YAML files where `saves: 0` (never saved). Flag entries that have stash items — those contain unrouted decisions/tasks. For entries with `saves: 0` and empty stash, check transcript file size to distinguish "opened and closed" from "real work, never saved."

Separate entries with stash (need review) from empty shells (safe to clear).

> **🐿️ tidy — unsaved sessions**
> 3 sessions with unrouted stash:
>  - stellarforge / squirrel:67b1e464 — 4 stash items
>  - glass-cathedral / squirrel:45dcf404 — 6 stash items
> 13 empty shells (no walnut, no stash) — safe to clear.
>
> ▸ review stellarfor