/refactor

• Point `/refactor` at the whole repo or one folder, with an optional batch budget
• Refuse to start without a config, without git, or with uncommitted changes
• Create a run ID and a repository lock so no other lightsout run touches the same tree

Keeps the entire cleanup as one diff you can read, revert, or resume

writes.lightsout/runs/<id>/manifest.json.lightsout/lock.json

• Search source files for repeated names, copied code, duplicate logic, oversized code, misplaced files, boundary violations, and dead exports
• Detectors that read types need the repo’s own TypeScript, and say so when it is missing
• Leave out anything already accepted as known debt, unless you asked for everything

Detection is deterministic code — no agent is ever asked to go find problems

READ FROM DISKlightsout.standards-baseline.json

• One batch is one kind of finding in one area — a package, a top-level folder, or the repo root
• The most mechanical kinds run first, twelve findings at most, and a finding spanning two areas gets its own batch
• Freeze the list to disk and work from it — never recompute it midway

Gives each agent a single coherent job instead of a pile of unrelated fixes

writes.lightsout/runs/<id>/worklist.json

• Run any code generator first, then lint, type checks, tests, build, and coverage
• Stop immediately if any gate is already failing
• Skip this on a resumed run when an earlier attempt already proved it green

Proves any later failure was introduced by this run, not inherited from the repository

writesmanifest.json.lightsout/runs/<id>/commands.jsonl

• Check again immediately before each batch starts
• If earlier batches already cleared these findings, close the batch and spend no agent
• Collect fresh size warnings for the batch’s files — the frozen ones cite line numbers that have since moved

Never pays an agent to fix something that is already gone

writesmanifest.json

• Batches run one at a time; the agent gets the findings, the files they live in, and your code standards
• Findings must be fixed or explained; size warnings are judged against your documented exemptions
• It may run only the commands your config allows, works under a time limit, and answers with one structured report

Changes structure only — the behavior has to survive untouched

writes.lightsout/runs/<id>/agents/stream-batch-NN-*.jsonlrejected-*.txt

• Re-run the gates, scoped to the packages that changed, with coverage always on
• Try up to two lightweight repairs when a gate goes red
• Send a coverage-only failure to a test-writing agent; a mixed failure goes back to the refactor agent first

Stops a batch that broke the build from reaching the next one

writesmanifest.json.lightsout/runs/<id>/commands.jsonl

• When the quick repairs run out, a read-only supervisor diagnoses the failure
• It either grants one guided retry or rules the failure a human problem
• If the gates are still red after that, the run stops with the diagnosis attached as evidence

Buys judgment exactly once, instead of retrying forever

writes.lightsout/runs/<id>/agents/stream-batch-NN-supervisor.jsonl

• Check again — the code rules, and a copied block that merely moved is not gone
• Gone counts as resolved; still there with nothing changed counts as declined, with the agent’s reasoning kept
• Partly fixed earns one more pass, and whatever survives that is recorded as declined

Work finished without a report still counts, and changed files come from git, minus generated output

writesmanifest.json.lightsout/friction.jsonl

• Three declines in a row end the run — the pattern is systemic, and more spend will not fix it
• A refusal on scope grounds counts as a decline and the run carries on
• A harness rate limit or your batch budget parks the run instead of failing it

Each batch is saved before the next begins, and declines are read back — resuming re-runs nothing

writesmanifest.json

• Check the whole scope once more and report findings before and after, one line per kind
• A parked run reports no burn-down — resume it to finish and measure
• Keep every batch outcome, retry, token cost, and point of friction in one folder

Turns the cleanup into a number you can check rather than a claim

writes.lightsout/runs/<id>/agents.jsonl.lightsout/friction.jsonl

• Read each declined batch alongside the agent’s own reasoning for leaving it
• Fix it by hand, or accept it as known debt in the baseline
• Review the working-tree diff and commit it — the engine never commits

Leaves the last call on unfixed debt with a human

writeslightsout.standards-baseline.json