[ohing504]

What changed

• clean --item checks only the named paths. Before, it rescanned the whole --path scope (default ~) and then kept the named artifacts. The scan now carries the item paths in its context:
  • The project walk enters only the directories that are an item or an ancestor of one. It still runs every check on them (prune, project markers, hidden-dir rule) with all their entries read, so an item is matched in the same project context as in a full scan.
  • Only the items are sized. Other results are dropped before classification.
  • brew cleanup --dry-run (13 s on the author's machine) runs only when an item is the Homebrew item.
• clean --json (needs --yes). It prints each item's result (trashed/freed/failed, or would_clean/would_fail with --dry-run) and error, plus trashed_size/freed_size, the --yes gate's skipped items, and vendor_cleanups. Errors before deleting stay on stderr as text with exit 1, as in text mode.

Why

The status-pane mod lists scan --json results and deletes with clean --item <path>... --yes. That call took about 28 s, and its result could not be parsed.

Measured on a real home with --dry-run (nothing deleted), old → new:

--item	old	new
a node_modules	28.6 s	1.4 s
~/.npm	27.9 s	1.0 s
a simulator device	31.4 s	1.5 s
node_modules + ~/.cache/uv (13 GB, pre-delete check)	33.8 s	4.7 s
~/Library/Caches/Homebrew (brew's own dry-run)	27.0 s	13.1 s
a path that is not an artifact	26.1 s	0.6 s

The text output was byte-identical in every case.

Tests

• internal/scanner/items_test.go runs a limited scan for every directory of a fixture and checks that the result at that path equals the full scan's. The fixture covers a nested project, an any-depth rule, a hidden ancestor, a pruned pnpm store, an artifact inside an artifact, global/HF/Homebrew caches and a stubbed brew. Breaking the hidden-dir rule or skipping item sizing makes it fail. A second test checks that brew's dry-run runs only for the Homebrew item.
• internal/cli/clean_test.go checks clean --json per-item results and totals with no other stdout, the dry-run with skipped, and the requirement for --yes.

Docs

• docs/SPEC.md § clean: a new --json example; a new --item paragraph on checking only the named paths; a new #### JSON (--json) subsection; Flow step 1.
• docs/ARCHITECTURE.md § Scanner Design: a new Limited scan paragraph (the scanner.WithItems contract).
• plugins/devclean/skills/devclean/SKILL.md: clean commands use --json; the scope note no longer says the rescan is slow; failures and the report now read from the JSON fields.
• No decision files changed.

🤖 Generated with Claude Code