mjmorales/janitor

Janitor Skill

You are the driver. prove never spawns Claude — you do. The split follows the engine boundary: the CLI owns inventory, token accounting, and every write; the memory-janitor agent owns the judgment of what is tribal knowledge versus rot; a human batch gate owns approval. Three hard floors govern every phase:

• Append-only, always. Nothing is deleted or edited in place in the store. Lore and annotations are cleaned by consolidation (a new distilled entry citing what it folds), the Codex by supersession (a pointer plus reason), contributor artifacts by rewriting the authored body (the one surface where in-place editing is the mechanism — the registry merge preserves it).
• Every write goes through claude-prove scrum (or the Write/Edit tools for decision files and contributor bodies). Never sqlite3, never ad-hoc scripts against .prove/prove.db.
• Every batch of writes is human-gated — one gate per team, one for the Codex. No silent cleanup.

What it cleans

| Layer | Store | Cleanup mechanism available | |-------|-------|------------------------------| | Team Lore | scrum_lores (mirrored into teams/<slug>.md, live recent-10 window) | Append a tech_lead-authored consolidation entry, then lore supersede each folded source; lore promote lifts project-wide entries into the Codex (approval auto-retires the source) | | Codex | scrum_decisions + .prove/decisions/*.md | decision supersede --by --reason; record consolidated replacements | | Annotations | scrum_annotations | Input signal only — durable findings get lifted into Lore or Codex; rows are never displaced | | Contributor artifacts | contributors/<slug>.md authored body | Direct Edit (frontmatter is registry-owned; never touch it) |

A superseded Lore entry leaves the team artifact's recent window the moment its replacement pointer lands (superseded_by = lore:<id> | decision:<id> plus a reason) while the row itself survives untouched in the store's history — the same append-only-with-supersession discipline the Codex follows. Consolidation bodies still name the ids they fold, so provenance reads in both directions.

Phase 0 — Scope and inventory (mechanical)

Parse arguments: zero or more team slugs (default: every team), optional --codex-only / --lore-only. Then inventory:

claude-prove scrum team list                       # teams in scope
claude-prove scrum lore list <slug> --live         # a team's LIVE Lore (JSON) — already-retired entries need no verdict
claude-prove scrum annotation list --target-kind team --target <slug>
claude-prove scrum decision list                   # the Codex
claude-prove scrum decision review-stale           # staleness signal (report-only)

Dump each list to .prove/scratch/janitor/<scope>.json (e.g. lore-funpack.json, codex.json) — these are the agent's inputs. Record the baseline footprint:

claude-prove prompting token-count "teams/*.md" "contributors/*.md" ".prove/decisions/*.md"

If everything in scope is empty, report that and stop — a janitor pass over nothing is a no-op, not a failure.

Phase 1 — Janitorial pass (judgment, read-only)

Dispatch one memory-janitor agent per team plus one for the Codex, in parallel via the Agent tool. Each prompt supplies:

• the scope (team <slug> or codex);
• the dump paths from Phase 0;
• artifact paths: teams/<slug>.md, each roster seat's contributors/<slug>.md (team scope) or .prove/decisions/ (codex scope);
• the team's seated tech_lead CT-UUID from the bundle roster (team scope) — the agent must not guess it.

The agent returns a single JSON plan: per-entry verdicts from the closed set keep | consolidate | promote | supersede | rewrite | noise, plus fully drafted bodies for every consolidation, promotion, replacement, and rewrite. Parse it; a "status": "blocked" plan names a missing input — fix and re-dispatch that scope only.

Phase 2 — Batch gate (one per scope)

For each team (and once for the Codex), present the plan with AskUserQuestion (header "Janitor"): per-entry verdict + one-line reason, the drafted consolidation/promotion titles, and the projected write list.

• Apply batch — execute Phase 3 for this scope as planned.
• Revise — operator adjusts verdicts/drafts; re-present.
• Skip scope — no writes for this team; plan is discarded.

Never merge scopes into one gate: a team's tech_lead-authored writes deserve their own approval.

Phase 3 — Execute (mechanical, CLI only)

Per approved scope, in this order:

1. Lore consolidations. Author each drafted body to .prove/scratch/janitor/<team>-<draft-id>.md with the Write tool (prose in a file, reviewable as text), append it as the seated tech_lead, then retire each folded source by pointer:

claude-prove scrum lore record <slug> \
  --body "$(cat .prove/scratch/janitor/<team>-<draft-id>.md)" \
  --author <tech_lead CT-UUID>
# then, per id in the draft's `folds` list:
claude-prove scrum lore supersede <folded-id> --by <new-entry-id> \
  --reason "folded into consolidation entry <new-entry-id>" --author <tech_lead CT-UUID>

The store enforces authorship on both writes: with a seated tech_lead the author MUST be that holder; with no tech_lead seated the write lands with a warning. Acting as the seat is the protocol — the batch gate is what authorizes it. A supersession resolves once: re-superseding an already-retired entry exits non-zero, so never re-run a fold that already landed.

2. Lore→Codex promotions. Three steps — stamp provenance, refine the body, resolve the gate:

claude-prove scrum lore promote <lore-id> --kind <adr|glossary|pattern> --title "<title>"
# write the agent's refined decision markdown over the raw-copied draft:
#   .prove/decisions/lore-promotion-<team>-<loreId>.md   (Write tool)
claude-prove scrum decision record .prove/decisions/lore-promotion-<team>-<loreId>.md --kind <same-kind>
claude-prove scrum decision approve <decision-id> --by <responder>

lore promote records the gated draft under the deterministic lore-promotion-<team>-<loreId> id and stamps source_lore_id; re-recording the file upserts the refined body onto the same row without touching either. Approval resolves the write-gate AND auto-retires the source Lore (superseded_by = decision:<id>). For glossary the responder must currently hold a tech_lead seat — use the team's tech_lead CT-UUID; for adr/pattern use the operator (claude-prove scrum contributor default show).

3. Lore that duplicates an existing accepted decision. No new row — retire the entry by pointing at the decision that already owns its substance:

claude-prove scrum lore supersede <lore-id> --by-decision <decision-id> \
  --reason "duplicates the accepted decision" --author <tech_lead CT-UUID>

4. Codex supersessions. Record any drafted replacement first (same record/approve flow), then point the old row at its successor:

claude-prove scrum decision supersede <old-id> --by <new-id> --reason "<why it changed>"

5. Contributor rewrites. Edit only the authored body below the frontmatter of contributors/<slug>.md; the frontmatter is registry-owned and a later contributor register merge preserves the body you wrote.

Phase 4 — Re-measure and report

claude-prove prompting token-count "teams/*.md" "contributors/*.md" ".prove/decisions/*.md"

Report per scope: token delta against the Phase 0 baseline, entries kept / consolidated / promoted / superseded / rewritten / left as noise-in-history, each promotion's decision id, and each team's count/live split from the artifact's lore: block. A zero-write pass with an all-keep plan is a valid, reportable outcome.

Guards

• Judgment is the agent's, writes are yours, approval is the operator's — never collapse the three.
• Provenance travels: every consolidation cites folded ids, every promotion cites its source lore id, every supersession carries a reason. A future reader must be able to trace why memory changed shape.
• Never re-run Phase 3 on a revised plan without re-gating the revised scope.
• Tech_lead impersonation is scoped: use the seat's CT-UUID only for the approved lore writes of that seat's team, nothing else.

References

| File | Purpose | |------|---------| | agents/memory-janitor.md | The judgment pass: five tests, verdict set, drafting rules, plan JSON | | references/design-principles.md | Engine boundary; append-only-with-supersession discipline | | references/interaction-patterns.md | The AskUserQuestion batch-gate pattern | | skills/curate/SKILL.md | The sibling lift: reasoning-log findings → Codex at milestone close |