Documentation / Reference

Map file format and operation protocol

Maps are tracked at maps/<map-id>/ inside a managed planning worktree, on branch map/<map-id>. IDs match [a-z][a-z0-9-]{0,79} and remain stable when titles/grouping change. Development checkouts identify the repository; they are never Map storage, staging indexes, or commit targets.

Enforced worktree boundary

The common Git directory contains local state under buildos-maps/: worktrees/<id>/, registrations/<id>.json, writer.lock, and sync/ publication receipts. Linked development worktrees share the same registered Map. Development branch switches do not switch the Map branch. The API returns workspace.path, workspace.branch, workspace.commonDirectory, and workspace.rootCommit; head means planning HEAD.

Creating the first Map uses git hash-object -w -t tree --stdin with empty input and git hash-object -w -t commit --stdin with fixed author/committer metadata to produce a deterministic, parentless empty planning commit. git update-ref refs/buildos/maps-root <root> <zero-oid> establishes its local anchor. Map creation uses git worktree add -b map/<id> <managed-path> <root>. It never uses development HEAD as its base, switches the development branch, borrows its staged work, or stashes/resets anything. Integration with a planning aggregation branch is a separate future operation; map-commit publishes only its per-Map branch.

Before reads/writes/commits, the manager checks registration, repository identity, separate Git directory, exact branch, empty root, ancestry, Map-ID trailers, absence of merges, and committed paths. Only its own maps/<id>/ files may exist in that history. Detached, moved, unregistered, symlinked, or contaminated worktrees fail without automatic repair. Existing branches without local registrations are never silently adopted. Existing development-checkout Maps require explicit migration; no files are moved or deleted automatically.

Library/CLI mutations and publication share a common-directory writer lock. Git environment overrides that redirect the index/worktree/Git directory are removed. Direct manual operations remain outside this cooperative boundary; observed mismatches stop the helper. Hooks run normally and are not sandboxed by a worktree; unexpected hook changes stop publication through post-commit validation.

maps/<map-id>/
  map.md
  map.yaml
  steps/<step-id>/step.md
  steps/<step-id>/verify.sh
  operations/<operation-uuid>.json

map.md describes the outcome, scope, and unresolved decisions. Each step.md describes instructions and acceptance criteria. Scripts are optional, ordinary tracked files. The reader never executes them. All paths must remain inside the repository and cannot contain symlinks. Files are limited to 1 MiB, 500 objects, and 2000 step files; each update writes at most 100 files.

Manifest

version: 1
title: Release the API
steps:
  release:
    title: API release
    kind: group
  x:
    title: Establish the schema
    parent: release
    status: todo
    depends_on: []
  y:
    title: Implement authentication
    parent: release
    status: todo
    depends_on: [x]
  z:
    title: Verify the integrated API
    parent: release
    status: todo
    depends_on: [x, y]
    checks:
      - id: integration
        command: bash "$MAP_ROOT/steps/z/verify.sh"
        cwd: .
    evidence: []

All objects have their own steps/<id>/step.md, including groups. kind defaults to step. parent references one group and controls the outline only. A group has no stored status, dependencies, checks, or evidence; it is complete when it has children and every child is complete. Empty groups remain incomplete. A work step has status todo, in_progress, or done. All dependencies must be complete before an executable step may be in progress or done. Dependencies can reference steps or groups; there is no implicit dependency on a parent. Group hierarchy and dependency graphs must be acyclic, including implicit group-to-child completion edges. Depending on your own containing group is therefore invalid.

Checks have unique id, command, and an implementation-repository-relative cwd (default .). Plan checks before implementation. Opening/saving never runs them. Execute checks explicitly against the implementation checkout, setting MAP_ROOT to the Map directory in the planning worktree and MAP_SOURCE_ROOT to the implementation checkout. Record the tested source commit/dirty digest in evidence revision and the planning revision/check definition in summary. Secrets belong in the environment, never in Map files.

For each required check, a done step requires its latest recorded evidence to be passed:

evidence:
  - check: integration
    result: passed
    revision: "<tested commit SHA>; dirty=<digest of tested changes if applicable>"
    summary: "Integration suite passed: 12 tests, exit 0."

Without checks, require passing evidence with check: manual, identifying who reviewed which acceptance criteria in summary. Evidence is an assertion recorded by the updating actor, not a cryptographic proof that tests ran. Record failed checks too. Freshness is reviewed by the agent: changing code/checks after a pass requires revalidation. The initial schema does not automatically invalidate evidence on arbitrary source changes.

Shared deterministic updater

In the MapForge checkout, run after installing MapForge:

mapforge list /absolute/project
mapforge show /absolute/project api-release
mapforge create /absolute/project api-release "Release the API"
mapforge update /absolute/project /absolute/request.json
mapforge validate /absolute/project api-release
mapforge test /absolute/project api-release [step-id]
mapforge commit /absolute/project /absolute/commit-request.json

Host applications call the same library functions. A request is a JSON object, with literal file contents rather than shell substitutions:

{
  "id": "api-release",
  "expectedHead": "<HEAD from show>",
  "expectedFingerprint": "<map.fingerprint from show>",
  "files": {
    "map.yaml": "<complete revised YAML>",
    "steps/new-step/step.md": "<complete Markdown>"
  }
}

The source CLI needs MapForge's Node dependencies. Repository arguments always identify the development checkout; the helper resolves the managed worktree. A commit request contains id, expectedHead, expectedFingerprint, message, and optional remote (default origin). It commits/syncs only refs/heads/map/<id> to a verified matching GitHub fetch/push repository. For injected workflows, locate the source CLI or use the library API for supported local document edits. If unavailable, prepare the request and report the missing capability. Never fall back to raw Git publication or development-checkout edits.

An update replaces named files with exact bytes. It supports graph/document edits and adding documents/scripts together. Physical deletion is unsupported. A no-op emits no receipt. The fingerprint is SHA-256 over a deterministic JSON array of manifest text, overview text, and sorted step-file path/hash pairs. Planning HEAD/fingerprint must match before applying and are rechecked before writing. Writers hold the common-directory lock and a worktree-local maps/.map-write.lock. Stale locks require inspection, never automatic takeover. Avoid concurrent direct edits during an update.

Before writing source files, the updater persists a receipt with state prepared. It contains the operation UUID, timestamp, exact paths, before/after SHA-256 hashes, expected Git HEAD, and executed Git argument arrays/results. After writes and validation it atomically finalizes the receipt as applied with the new fingerprint. Multi-file writes are recoverable through this journal, not a filesystem-wide atomic transaction. An interruption leaves prepared and blocks normal reading/updating. Inspect actual files against every recorded before/after hash; resolve the intended outcome explicitly before finalizing or superseding that receipt. Never claim an interrupted update succeeded.

Commands mapped to Git

Agent command File behavior Git behavior
/map Create/refine a Map in its managed worktree Create an independent planning root and map/<id> worktree when needed; never switch the development checkout
/map-start Implement ready work in the development checkout; checkpoint in step Markdown, run checks, and update reviewed completion through the helpers Read source/planning state; no staging, commit, or push
/map-update Validate and replace declared files in the planning worktree; record receipts Verify planning registration/history and read planning HEAD twice; no staging/commit/push
/map-status Read/validate documents and receipts Read status/diffs/branch/cached upstream; no fetch
/map-test Run ready declared checks in the implementation checkout; append evidence via the updater Read source HEAD/diff/untracked hashes and planning preconditions; no stage/commit/push
/map-commit Call the enforced CLI commit operation; record sync progress Verify worktree/history → fetch only the Map branch → stage exact paths in the planning index → commit → push the verified SHA to map/ → verify remote SHA

The full publication sequence is in the map-commit command. Updates, local commits, and verified GitHub publication are separate recorded states. /map-commit explicitly requests both commit and publication through the helper. Ordered operation receipts are tracked with the Map; local sync receipts live under the common Git directory's buildos-maps/sync/. The UI provides local authoring/outline navigation; publication requires invoking the commit helper. No raw Git fallback is permitted.