2026-06-23 · repository-refactor

Overnight project refactor as PR-sized slices

A broad refactor can run overnight while staying split into human-sized review units.

The operator can wake up to reviewable PR-sized refactor slices instead of a single giant autonomous diff.

refactorPR slicestodo evidence

Case context

This case addresses the risk of unattended refactoring: a long-running agent can mix cleanup, behavior change, discoveries, and stale plans into one broad diff.

The public evidence is not a private overnight screenshot. It is the control-plane behavior already documented and smoke-tested in the repository: todo lifecycle, successor/supersede, validation writeback, and review packets. `todo-lifecycle-cli-smoke.py` carries regression coverage for successors, supersede, handoff, and self-merge.

Repository evidence

Proof

Long unattended refactors can split into moderate PR slices instead of one unreviewable diff.

LoopX intervention

loop, todo follow-up, supersede, PR-sized slices

1PR-sized slice at a time

3successor/supersede/handoff routes

1review gate for broad risk

0giant-diff target

Successor path

`docs/lark-kanban-control-plane-adapter.md` says real successors use `todo complete --next-*`, while replacements or narrower splits use `todo supersede --next-agent-todo`.

Side-agent completion

`docs/heartbeat-automation-prompt.md` requires nontrivial completion to create a successor todo or a no-follow-up rationale.

CLI validation

`examples/todo-lifecycle-cli-smoke.py` covers `--next-agent-todo` successors, `todo supersede`, claim inheritance, handoff successors, same-agent handoff rejection, and side-agent self-merge evidence.

Review shape

`loopx review-packet` packages open todos, claimed_by, and handoff state for reviewer consumption.

LoopX behavior

1
The current refactor slice must stay reviewable; overnight discoveries do not all land in one PR.
2
New discoveries become follow-up todos; changed routes supersede stale todos.
3
Each slice carries focused validation or doc/contract smoke evidence rather than raw agent traces.
4
Broad or unclear-risk slices route to review handoff instead of self-merge.

What the user sees

The user can let a refactor run overnight and wake up to bounded review units plus remaining todos, not one unreviewable giant change.

The project can move quickly while the review surface remains human-sized.

Repository sources

kanban control-plane adapterdocs/lark-kanban-control-plane-adapter.mdheartbeat prompt contractdocs/heartbeat-automation-prompt.mdtodo lifecycle smokeexamples/todo-lifecycle-cli-smoke.pycase narrativedocs/showcases/cases/0623-overnight-project-refactor.md

Evidence boundary. Public-safe pattern case only; no private screenshots, raw chats, internal planning notes, local paths, credentials, raw logs, or unpublished project artifacts.

Case note