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 bordered 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 stellarforge stash / review glass-cathedral stash / clear empty shells / skip
╰─

1f. Orphan Files at World Root

Flag anything at the world root that isn't an ALIVE folder (01_Archive/ through 05_Experiments/), .alive/, .claude/, or dotfiles. Nothing should live loose at root.

1g. Index Staleness

Check if .alive/_index.yaml exists and when it was last generated. If it doesn't exist or is older than 7 days, offer to regenerate by running generate-index.py.

Pass: index exists and is recent. Fail: missing or stale — offer to regenerate.

Phase 1 Results

Present all 7 results together. Passing checks get one line. Failures expand.

╭─ 🐿️ root audit — 7 checks
│
│  ✓ 1a. ALIVE structure — intact
│  ✓ 1b. Inputs buffer — clean
│  ⚠ 1c. Cross-walnut links — 2 undeclared connections
│  ✓ 1d. Walnut integrity — all complete
│  ⚠ 1e. Unsaved entries — 3 with stash, 13 empty
│  ⚠ 1f. Orphan files — 2 at root
│  ✓ 1g. Index — current
│
│  3 issues to resolve.
╰─

Then ask which to fix:

╭─ 🐿️ root audit — which to fix?
│
│  1. 2 undeclared cross-walnut connections
│  2. 3 unsaved sessions with stash (11 items total)
│  3. 2 orphan files at world root
│
│  ▸ which ones? (numbers, "all", or "skip")
╰─

For each the human picks, propose the specific fix:

╭─ 🐿️ proposed fixes
│
│  1. Add [[ryn-okata]], [[jax-stellara]] to stellarforge key.md links:
│  3. Move AGENTS.md → glass-cathedral/raw/,
│     delete disaster-recovery-extraction.md
│
│  ▸ go / change something / skip
╰─

On "go": dispatch parallel general-purpose subagents to execute — one per fix. Each subagent reads the file, makes the edit, returns confirmation. Main context does not touch files.

╭─ 🐿️ root audit complete
│  7 checks. 3 issues, 2 fixed, 1 skipped.
│  ▸ continue to walnut audit / done
╰─

Phase 2 — Walnut Summary

Single subagent scans all walnuts. For each walnut, read ONLY _kernel/now.json (v3 flat path) and _kernel/key.md frontmatter (rhythm, type). Frontmatter only. Do not read full files.

Return a health table. The main context presents it:

╭─ 🐿️ walnut health summary
│
│   #  Walnut               Type         Health    Updated         Rhythm
│   1. glass-cathedral             experi