`append`
mapsplice append <target> <file-to-append>
append is phase-only in the current release. The fragment file must contain
one or more phases, and those phases are appended to the end of the target
roadmap.
When the target roadmap is gate-clean, append preserves untouched existing
task lists byte-for-byte, including deliberate blank lines and nested body
spacing. Task lists are regenerated only when the operation changes that list,
for example by renumbering, replacing, deleting, inserting tasks, or rewriting
dependency text inside the list.
`insert`
mapsplice insert <target> <anchor> <file-to-insert>
mapsplice insert --after <target> <anchor> <file-to-insert>
insert places sibling content before the addressed anchor by default. Pass
--after to place the fragment after the anchor instead.
Task-level inserts preserve unchanged task source byte-for-byte, including continuation-line indentation.
Examples:
mapsplice insert docs/roadmap.md 8 new-phase.md
mapsplice insert --after docs/roadmap.md 8.2.3 new-task.md
During a structural splice, unchanged target tasks and addendum sub-tasks
retain their exact source wrapping and indentation, including required blank
separators around nested bodies. Exact source is reused only while it remains
formatter-stable. Here, formatter-stable means that ordered or nested list
markers and code-fence delimiters remain stable; instability in either causes
canonical rendering. Changes to an item's own number or text,
dependency-related content, or structural descendants invalidate that source,
so the item may be rendered canonically.
`delete`
mapsplice delete <target> <anchor>
delete removes exactly one addressed phase, step, or task. Any later items at
the same or deeper levels are renumbered as needed.
Task-level deletes preserve unchanged surviving task source byte-for-byte, including continuation-line indentation.
Canonical output can include <!-- mapsplice: preserve body list boundary -->
when a deleted addendum leaves same-kind body lists that must remain distinct.
The marker remains stable while its task remains in the roadmap. Adjacent tight
bullet-list runs merge into one list when the separating addendum is removed.
`replace`
mapsplice replace <target> <anchor> <file-to-replace-with>
replace removes the addressed item and splices in one or more sibling items
from the fragment file. Replacing a phase with multiple phases is supported,
provided the fragment itself contains phases.
Task-level replacements preserve unchanged sibling task source byte-for-byte, including continuation-line indentation.
Canonical output can include <!-- mapsplice: preserve body list boundary -->
when replacement output must keep same-kind body lists distinct. The marker
remains stable while its task remains in the roadmap. Adjacent tight
bullet-list runs merge into one list when the separating addendum is removed.
Inserted or replaced tasks, and tasks whose number or dependency reference changes, or whose sub-task content is edited, are rendered canonically.