docs: let maintenance clones self-heal and abort without leaving debris

A failed nightly run left edits in the maintenance clone, and every later run
correctly refused to work on a dirty worktree, so one failure stalled the whole
pipeline until morning.

Maintenance task commands now recognise a gitignored .maintenance-clone marker.
In a marked disposable clone they discard leftover debris, return to main, and
continue; in a human working copy they still stop and touch nothing.

Add an explicit abort protocol: revert your own edits, confirm the worktree is
clean, release the claim, and report. Restore the honest skip that the
complete-file rule had squeezed out, since a laundered fix is worse than a
documented skip, and describe how to handle a file that is entirely an
external-data boundary instead of inventing generic JSON contracts.
This commit is contained in:
Bohdan Triapitsyn
2026-08-17 21:49:33 +03:00
parent d9f1c0d44c
commit 344c1b3ce3
6 changed files with 106 additions and 7 deletions
+14 -1
View File
@@ -13,7 +13,20 @@ First, verify the worktree is safe to use:
`git status --porcelain`
If the output is not empty, stop immediately and report that the worktree has uncommitted changes. Do not stash, reset, discard, or switch branches.
If the output is not empty, decide which of two situations you are in.
If the repository root contains a `.maintenance-clone` marker file, this working copy is a disposable clone dedicated to unattended maintenance. Nothing in it is human work in progress, so leftover changes are debris from an earlier task that failed to clean up after itself. Recover the clone rather than stopping:
```
git checkout -- .
git clean -fd
git checkout main
git pull
```
Report exactly which files you discarded, then continue with the task. A failed predecessor must not be able to jam the pipeline for every later run.
If the marker file is absent, this is a working copy a person uses. Stop immediately and report that the worktree has uncommitted changes. Do not stash, reset, discard, commit, or switch branches.
List the active batches: