feat(index): list, classify and prune stale colgrep indexes with a housekeeping prompt

[LittleCoinCoin]

Seventh campaign, index_housekeeping (R01/R02 in __reports__/index_housekeeping/). Gives agents the facts and the one tool needed to keep colgrep's index store lean, plus the changelog fix carried from the harness_wiring cycle.

What changes for a client

Surface dump-and-diff (Client.list_tools() / list_resources() / list_resource_templates() / list_prompts() JSON on main vs this branch):

• list_indexes: description and input_schema changed (new stale_only argument). Its IndexInfo rows gain path_exists, size_bytes, last_modified, shadowed_by, stale; IndexList gains store_root, total_bytes, total. The four legacy tokens stay at the front of every text block.
• new tool index_prune(classes, days, max_searches, dry_run=true, confirm=false) — destructive, idempotent, not open-world.
• doctor: tool listing identical; structured_content gains hints ([INDEX_STORE_STALE] …, [INDEX_STORE_UNKNOWN] …).
• colgrep://indexes: description changed; serves the same enriched IndexList.
• new prompt housekeeping(days="30").
• search, find_files, expand, index_status, index_build, index_clear, the other resources, the status template and the three existing prompts: byte-identical.
• new codes INDEX_STORE_UNKNOWN, INDEX_STORE_STALE in colgrep://errors.

Why

Measured on the maintainer's machine on 2026-09-13: 165 indexes, 3.3 GiB; 65 orphaned (path gone), 46 shadowed (inside another indexed project), 7 machine-state, 4 cold. list_indexes showed none of that, so a clean-up cost one index_status per guess and one confirmed index_clear per project.

The probe that shaped the design (R02)

colgrep clear <gone path> exits 1 with Error: No such file or directory (os error 2) and leaves the index directory in place, so index_prune deletes store directories itself, guarded by the directory being a direct child of the store root and its project.json naming the candidate at deletion time. It never runs colgrep clear (on a shadowed path that would clear the folding ancestor). The store root is the parent of one Index: line, never a platform path.

Read-only dogfood against the real store

store.index_list over this machine's 165 indexes: 321 ms including the --stats and one status spawn; classification 65 orphaned / 8 machine-state / 46 shadowed / 4 cold / 42 live. Nothing was deleted; the real index_prune was not run.

The first pass classified /private/tmp (2 434 units, the project every session scratchpad folds into) as live: macOS's per-user temp directory sits under /var/folders, so nothing named /tmp as machine state. fix(index): treat the posix /tmp as machine state in the classifier and the hook gate adds it to the shared roots in both the hook and the server; the regression test failed against the old roots on macOS (on Linux the two directories coincide, so it passed there before the fix).

Changelog fix (build(repo))

cz changelog --dry-run 0.3.0..0.4.0 with incremental mode off reproduces the committed CHANGELOG.md before the change; after it the diff removes exactly the (PR #7) line of v0.4.0 and the (PR #6) merge's two lines of v0.3.0 (GitHub had copied the PR title into that merge's body). commitizen matches changelog_pattern against the whole message, so the lookahead stops at the first newline; a $-anchored first attempt changed nothing and the new test in test_changelog.py fails against it.

Portability

First exercise of: the hook gate's roots on Windows with the os.name == "posix" branch skipped, reading a synthetic store under tmp_path on Windows, Path(index_path).parent on a drive-rooted Index: line, os.scandir size walks, shutil.rmtree of store directories. The pure classifier takes home and the machine-state roots explicitly because the Windows runner's temp directory sits under the home directory (R01 risk 2). Read the Windows job, not just the badge.

Gates (from server/)

• uv run pytest: 306 passed, 1 skipped
• uv run ruff check: All checks passed!
• uv run ruff format --check: 46 files already formatted
• uv run cz check --rev-range main..HEAD: Commit validation: successful!
• claude plugin validate . and ./dev: Validation passed
• dev/skills/landing-and-release/scripts/probe_cz_check.sh: all expectations met

Unfinished

Nothing planned in R01 is left out. Not done, deliberately: the real index_prune was not run against the maintainer's store (the PI decides when); no dirtree-rdm roadmap (R01 D10, step commits).

🤖 Generated with Claude Code