Documentation / Agent workflows

Commit and sync a Map

Read Working safely and Map format and operations. :map-commit, /map-commit, and $map-commit select this workflow. Invocation authorizes one Map's scoped commit and ordinary GitHub push, never development commits, force-push, merge, rebase, reset, stash, or automatic migration.

Use the enforced helper

All Map commits and publication MUST go through the MapForge CLI's commit operation. Do not implement this workflow with ad hoc Git staging, commit, checkout, worktree, or push commands. Branch naming alone is insufficient: the helper verifies the registered worktree, separate index, independent history, receipt-backed write set, and remote target. If the helper is unavailable, prepare the request and report the missing capability. Do not fall back to committing from the development checkout.

  1. Resolve one Map ID and the intended development repository root. Locate the MapForge CLI and run mapforge show <development-repo> <id> using its installed CLI. Inspect the returned Map, planning HEAD, workspace path/branch/root commit, and operation receipts. Let the helper resolve the worktree; never reuse the terminal's Git index.
  2. Review the Map, checks, evidence, and changes. Apply changes with :map-update first. Verify the intended GitHub remote identity with read-only inspection; use the configured remote name (default origin). Do not alter remotes to make publication succeed.
  3. Write a literal JSON request to a temporary file, with id, expectedHead (the planning HEAD), expectedFingerprint (the Map fingerprint), a specific message, and optional remote. Preserve actual newlines; do not use shell substitutions for file content.
  4. Run mapforge commit <development-repo> <request.json> using the installed MapForge CLI. Do not run this merely while designing or discussing a Map.
  5. Report the returned planning branch, commit, remote ref, and sync receipt. Only say synced when the helper returns synced: true after verifying the remote SHA.

Enforced Git sequence

The helper obtains the common-directory writer lock and resolves <common-git-dir>/buildos-maps/worktrees/<id> on map/<id>. It validates repository/worktree registration, the separate Git directory, independent empty planning root, absence of merges/development history, and Map-ID commit trailers. Git environment overrides that could redirect an index, Git directory, or worktree are removed.

Before staging it checks the expected planning HEAD/fingerprint, ordered operation-receipt chain, source hashes, and immutable committed receipts. An already staged planning index, symlinks, unrecorded edits, or unrelated files stop the operation without cleanup.

Publication requires one credential-free GitHub fetch URL and one matching push URL. Its destination is always refs/heads/map/<id>; a development upstream cannot redirect it. The helper reads the remote ref, fetches only that Map branch with --no-write-fetch-head, and requires the remote SHA to be an ancestor of planning HEAD. Divergence stops publication.

The exact write commands run with git -C <verified-planning-worktree>:

  • git add -- <exact-reviewed-paths...>
  • git commit -m "map(<id>): <message>" -m "<Map-ID and Map-Operation trailers>"
  • git push <remote> <verified-commit-sha>:refs/heads/map/<id>
  • git ls-remote --exit-code <remote> refs/heads/map/<id>

Staged/committed hashes, parent, changed paths, branch, and ancestry are rechecked. Hooks run normally; unexpected hook changes stop publication. A successful local commit remains intact if pushing fails. Before retrying, inspect the current planning snapshot, sync receipt, and remote state; do not reset or replay a stale mutation.

Local sync receipts live at <common-git-dir>/buildos-maps/sync/, recording command argument arrays, exit status, output, phase, and commit ID. A receipt is written before staging/publication and updated after each command. Interrupted operations never report success. Tracked operation receipts and commit trailers link file updates to their planning commits.