pm delete leaves an undiscoverable tombstone: history ledger survives the item but no command, health check, or gc scope reports it #708

pm delete correctly retains the item's history ledger as a tombstone, but nothing in the tooling can tell you that tombstone exists. No command enumerates it, no diagnostic reports it, and no pm gc scope reclaims it. The only way to discover one is to ls .agents/pm/history/ and diff the basenames against the item directories by hand.

Verified on 2026.7.25 in a clean throwaway workspace.

Reproduction

mkdir /tmp/tomb && cd /tmp/tomb && git init -q .
pm init --pm-path .agents/pm
pm create --title "Residue probe" --type Chore --author probe --pm-path .agents/pm
#  -> pm-ladp
pm delete pm-ladp --pm-path .agents/pm --force

The item file is gone and the ledger remains, with a correctly appended delete op:

$ ls .agents/pm/chores/ .agents/pm/history/
.agents/pm/chores/:        # (empty)
.agents/pm/history/:  pm-ladp.jsonl  _workspace.jsonl

$ python3 -c "import json;[print(json.loads(l)['op']) for l in open('.agents/pm/history/pm-ladp.jsonl')]"
create
delete

So retention is clearly deliberate — that part is right, and this issue is not asking for the ledger to be deleted. The problem is everything else:

pm health output does contain orphaned_paths / orphaned_path_rows keys, but those belong to the vectorization/index check and never populate for a tombstoned history stream — which makes the situation more confusing, not less: an agent that greps health output for "orphan" finds the vocabulary present and concludes the check covers this case.

Why this matters for agents

1. Undiscoverable state. An agent has no supported way to answer "does this workspace contain tombstoned streams?" pm show denies the id exists while pm history happily serves it. Two built-in commands disagree about whether pm-ladp is a thing, and neither mentions the tombstone concept.

2. It breaks the documented commit convention. Every pm-CLI-based workflow we run enforces "a .toon must be committed together with its history/<id>.jsonl sibling". After a delete, git status shows an untracked history/<id>.jsonl with no .toon — the inverse case the convention has no answer for. Agents either commit a ledger for an item that does not exist, or delete an intentional audit record. Both are wrong and the tooling gives no signal which is intended.

3. Silent unbounded accumulation under multi-agent merge. Tombstone ledgers are append-only files with unique names, so they merge cleanly by construction and never conflict. Across many agents and branches they accumulate indefinitely with no command to list them, no check to count them, and no gc scope to reclaim them. This is precisely the class of drift pm health exists to surface.

4. pm delete gives no hint. Its output (previous_status, changed_field_count: 1) does not mention that a ledger was retained, so the residue in git status reads as a bug in the caller rather than intended behaviour.

Requested

Any one of these would close the discoverability gap; the first is the most useful:

• A pm health check (or a field on the existing storage/integrity check) that counts history streams with no corresponding item file and lists them up to a cap — status: ok with an informational count is fine, since this is legitimate state, not corruption.
• A way to enumerate them, e.g. pm list --tombstoned or a tombstones section in pm health --detail deep.
• A pm gc --scope tombstones (opt-in, never in the default set) for workspaces that do not want to retain deleted-item audit trails, plus a retention_days setting alongside the existing checkpoints.retention_days.
• Mention the retained ledger in pm delete's own output (e.g. history_retained: ".agents/pm/history/<id>.jsonl") so the caller knows the file is intentional and must be committed.

Documenting the tombstone contract in pm delete --help would help regardless of which of the above is chosen: right now the help text says only "Delete an item and record the change in history", which does not convey that the ledger file survives the item.