docmend

Purpose

Bulk edits across a documentation tree are easy to start and hard to undo. docmend exists so that a sweeping change to many files is a controlled operation with a plan, a verification step, and a way back.

The intended operator is anyone maintaining documentation large enough that hand-editing is not practical and blind scripting is not safe.

Operating model

Five stages, deliberately separate: scan establishes what is there, plan produces the proposed change as an inspectable artefact, apply performs it, verify checks the result against the plan, and restore reverses it.

A dry run is the default. Producing the plan is not a preview of the operation; it is the operation until someone chooses otherwise. A run that is interrupted partway can be resumed rather than restarted, because the manifest records what actually completed.

Practices

Control is the stage separation. Each stage has one job, and the consequential one is opt-in.

Verify is the check between the plan and the result. Without it, “apply” reports success on the strength of not having crashed.

Recover is the manifest, restore, and resume path — the reason an interrupted run is a nuisance rather than an incident.

Protect is the dry-run default and the refusal to act on an unreadable or ambiguous plan.

Architecture

The manifest is the centre of the design. It records what a run intended and what it achieved, and both restore and resume read from it. Everything else is arranged so the manifest cannot become a fiction.

The rejected shortcut was in-place editing with backups written alongside. Backups beside the file are lost with the directory they document.

Evidence

The repository is public under MIT and carries published releases.