claude-ops/audit-install-state: flag the files the engine reads by content, and stop calling .last-cleanup the sweep's watermark as fact

[kyle-sexton]

Context

The engine opens exactly three files by content: settings.json, .last-cleanup, and plugins/.last_inuse_sweep (CONTENT_READ_ALLOWLIST). The retention section uses .last-cleanup as measured evidence that the sweep ran, while the entries table reports the same file as unclassified-report-only with no-upstream-row. Both statements are true, but a reader sees the engine trust a file it says nothing documents, with no field linking the two.

The research behind this issue (raw docs fetched 2026-09-11) found that .last-cleanup and plugins/.last_inuse_sweep are undocumented in claude-directory.md, settings-reference.md, monitoring-usage.md, and the CHANGELOG through 2.1.268. The reading that .last-cleanup is the retention sweep's timestamp sentinel is community-sourced and observation-based (it is 24 bytes and was restamped mid-session), and its cadence is disputed in community sources. Yet reference/surfaces.md and SKILL.md currently assert it as "the sweep's own watermark" as though documented.

A new surface class is the wrong fix. staleness_reading maps KEPT and AUTHORED to keep and everything unrecognised to unclassified-report-only, so moving settings.json (today AUTHORED, "Upstream: do not delete") into a new class would demote a never-delete file. surface_evidence is measured for any non-unclassified surface, so a new class would attach measured to two files that have no upstream row. And classify_entry matches top-level names only, so plugins/.last_inuse_sweep cannot receive its own surface without a classifier change.

Proposed work

• Add an orthogonal per-entry flag, content_read: true, on the three allowlisted paths (the report already carries content_reads.paths; this puts the same fact on the entry rows so the retention section and the entries table agree). Surfaces are unchanged: settings.json stays AUTHORED.
• For the two sentinels, add a why that states the observed role with evidence observed-undocumented (shares the vocabulary extension from the remote-tree issue if that lands first; otherwise add it here with the schema bump) and never claims the product manages them.
• Correct reference/surfaces.md and the SKILL.md Phase 2 text: ".last-cleanup advancing is direct evidence the sweep ran" becomes a statement that it is an undocumented sentinel observed to advance when the sweep runs, with a four-part record and a recheck trigger (claude-directory.md gains a row, or the CHANGELOG names the file).
• Tests: the flag appears on exactly the allowlisted paths; settings.json still reads keep.

Acceptance criteria

• Every entry whose path is in CONTENT_READ_ALLOWLIST carries content_read: true; no other entry does.
• settings.json still reports surface authored and reading keep.
• .last-cleanup and plugins/.last_inuse_sweep carry an evidence tag that is not measured for their role claim, and their why does not say the product manages them.
• reference/surfaces.md and SKILL.md no longer state the watermark role as documented fact; both carry the four-part record.

References

• Research ledger: claim 5 (.last-cleanup undocumented in claude-directory.md, settings-reference.md, monitoring-usage.md, CHANGELOG; semantics MEDIUM; cadence unknown), 2026-09-11.
• plugins/claude-ops/skills/audit-install-state/scripts/install_state.py: CONTENT_READ_ALLOWLIST, SURFACE_TABLE settings.json row, classify_entry, staleness_reading, surface_evidence, content_reads assembly.
• reference/surfaces.md (the .last-cleanup row), SKILL.md Phase 2.
• claude-directory.md "Don't delete ~/.claude.json, ~/.claude/settings.json, or ~/.claude/plugins/" (fetched 2026-09-11).

Metadata

Field	Value
Category	unspecified
Area	unspecified
Ecosystem	unspecified

---

Generated by Claude Code