disk-hygiene: persist a catalog of investigated entries — record shape, scope, investigation procedure, and operator answers

[kyle-sexton]

Drafted by an AI agent from an operator-confirmed interview (run 20260908-home-d1).

Parent

Parent: #4004. Refs #3858, which implements ranking signals computable from existing snapshot data. That issue makes the component notice more; this one makes it remember. They are complementary and neither substitutes for the other: signals rank what to look at, the catalog records what looking at it concluded.

Covers four confirmed decisions together — record shape, catalog scope, investigation procedure, and what happens when the owner is still unknown — because they are one artifact and one pass.

Problem

The component investigates and then forgets.

On this run, deciding that .sbx-denybin (104 bytes, four stub ssh/scp batch files) was removable took a nine-source investigation: User PATH, Machine PATH, the claude-remote-control scheduled-task action, .claude.json, .codex\config.toml, .claude, the chezmoi source, and the sandbox checkout. That reasoning exists only in a report in the operator's data directory. The next run re-derives it from nothing, or does not.

Worse are the entries kept because the investigation ran out of road, with no way to record that it did:

• .cache\verifier-scratch — 173 KB, contains a .git, newest file 2026-09-02, no config anywhere references it. Owner unknown, so kept.
• .cache\performance-harness — 87 bytes, same shape. Owner unknown, so kept.
• ansel — empty, created 2026-09-01, zero provenance anywhere on the machine. Name-only, so kept.

Each of those will be re-investigated, reach the same dead end, and be kept again, every run, forever. The operator knows the answer for at least one of them and was never asked in a form the component could retain.

What to build

One artifact under the plugin data root: catalog.json plus a rendered CATALOG.md.

Record shape

One record per catalogued entry:

• path
• identity — device, inode, kind
• owner
• provenance — a narrative of 2-4 sentences
• evidence — a list, each item carrying its source: a file path, a command, or a URL
• disposition
• tier
• size
• first_seen_run, last_seen_run, last_verified
• source — engine or human

How a record is used

• The scan annotates a matching entry with prior_disposition.
• The report leads with new or changed entries; unchanged ones get one line each. This is the point of the artifact: a re-run of a catalogued home directory should be short.
• Identity or descendant-set change invalidates a record. A moved inode or a changed child set means the thing being described is not the thing that was described.
• A record is a hint, never authorization. The same rule the component already applies to filename hints. A catalogued remove disposition does not shorten the approval ceremony, does not skip a preview, and does not survive a failed revalidation.

Catalog scope

Catalogue:

• every immediate child of the target,
• every hinted or empty entry at any depth,
• every entry flagged out of place — no protected reason, no recognizable app or config convention.

Deeper entries catalogue at owner level: one record per owning tool or product, not one per file.

The operator's constraint, verbatim: "Nothing that looks out of place is skipped." An out-of-place entry is investigated, catalogued, and inventoried with enough context to justify its disposition, whatever that disposition turns out to be. "Small", "empty", and "probably fine" are not reasons to skip; they are findings to record.

Investigation procedure

The skill ships a required local procedure, run per catalogued entry:

• manifests and READMEs
• config file contents
• Get-Command (or the platform equivalent)
• running processes
• scheduled tasks
• PATH, both user and machine
• installed programs
• git remotes and status
• dotfile and settings references

Escalation to /discovery:research is presence-gated and permitted only when the local procedure finds no owner. /discovery:explore applies only to repository strays.

Unknowns

The report ends with one question per entry whose owner is still unknown after the local procedure and any escalation.

The operator's answer is written into the catalog as human-sourced provenance (source: human) and is not asked again while identity holds. Until answered, the entry's disposition stays keep.

Design constraints

• The catalog records conclusions and their evidence; it never records an approval.
• An entry with source: human provenance is not re-investigated by the local procedure while its identity is unchanged, but it is still re-verified for identity.
• Unknown must remain visibly unknown. An entry no investigation resolved reads as unresolved, not as low-priority — the failure mode this whole artifact exists to prevent is a dead end quietly aging into an assumption.
• The rendered CATALOG.md is for the operator to read without running anything.

Acceptance criteria

• catalog.json and a rendered CATALOG.md are written under the plugin data root, with the record shape above.
• A scan annotates matching entries with prior_disposition, and the report leads with new or changed entries while giving unchanged ones one line each.
• A change to an entry's identity or descendant set invalidates its record, demonstrated by a test.
• A catalogued disposition never shortens or skips any approval, preview, or revalidation step, demonstrated by a test.
• Catalog scope covers every immediate child, every hinted or empty entry at any depth, and every out-of-place entry; deeper entries are catalogued at owner level.
• The local investigation procedure ships in the skill, is required per catalogued entry, and its sources are enumerated.
• /discovery:research is invoked only when the local procedure finds no owner, and only when present.
• The report ends with one question per still-unknown-owner entry; an operator answer is persisted with source: human and is not re-asked while identity holds.
• An entry with an unanswered question keeps disposition keep.
• scripts/affected-tests.sh --run selects and passes the suites mapped to the changed files.

Out of scope

• Ranking signals, which are disk-hygiene: implement the ranking signals the provenance mandate currently rests on nothing #3858.
• Any mechanism by which a catalog record grants deletion authority.
• Cataloguing inside protected shell roots, which are not walked at all.

[kyle-sexton]

A concrete case for this from a v0.23.12 run on Windows. After researching C:\eSupport (an ASUS factory driver package, 7 GB), the user decided to keep it and said "Don't flag it in the future". The only current mechanism is additional_protected_path_globs in the standing policy file ~/.claude/disk-hygiene.json. That works, but:

• it records only a glob, not the decision, the reason, the evidence, or when to re-check it;
• globs are relative to the scan target, so eSupport only matches when C:\ is scanned in root-children mode;
• it marks the entry protected, which is stronger than "investigated, keep, don't re-raise".

The user wants "keep and don't re-raise" operator answers to be a standard, first-class plugin feature, recorded and reused, not a hand-written protection glob.

[kyle-sexton]

This was generated by AI during triage.

Human-gated. Open decision: catalog record schema, scope, and investigation-procedure design (cross-cutting, no catalog.json/CATALOG.md exists today)

[kyle-sexton]

An abandoned Cursor attempt branch cursor/4008-investigated-catalog-6ca3 at commit 802833421be9a077dba09441fb6db44e59f4d95f is being deleted in a repository cleanup. It never opened a PR, and this issue stays open to be redone. Summary: 1 commit(s) beyond main, tip "802833421 feat(disk-hygiene): persist an investigated-entry catalog"; 11 files changed, 1016 insertions(+), 6 deletions(-).

To restore it: git push origin 802833421be9a077dba09441fb6db44e59f4d95f:refs/heads/cursor/4008-investigated-catalog-6ca3

[kyle-sexton]

This was generated by AI during the 2026-09-29 audit of the Cursor run.

Stranded work, recorded here so it is not lost. The issue stays open and needs-human.

PR #5127 (Closes #4008) was closed by operator decision because the schema, scope and procedure decisions on this issue are still open. Its implementation (lib/engine_grammar.py, scripts/investigated_catalog.py, test_investigated_catalog.py) now survives only at refs/pull/5127/head (cd4e8560e6c307310c01bbebeeb5d990929d3a7a). The branch cursor/4008-investigated-catalog-v2-37e9 no longer exists on origin.

Retrieve with git fetch origin pull/5127/head.

Reuse needs:

• Rebase. Its 0.29.1 bump sits on a stale 0.28.9 base while main's disk-hygiene plugin.json is 0.28.15, so renumber.
• Fix the lint-2 failure.
• Wait for the owner's schema decision on this issue. The work must not merge before that decision.

No new decision packet: this issue already carries the open decision (the triage comment above).

[kyle-sexton]

Owner decision (2026-09-29): Approve building the disk-hygiene investigated-entry catalog as specced (catalog.json plus CATALOG.md, hint-only records, invalidated on inode or child change), built in slices with the first-class "keep, don't re-raise" answer first. Next: an agent implements it in slices, starting with recording and reusing keep/don't-re-raise operator answers and the scan's prior_disposition annotation; the abandoned work at refs/pull/5127/head can seed it after a rebase.