Patch.md

Patch.md is an experimental Git-native format and agent workflow for preserving the intent behind downstream software changes and reapplying that intent as upstream evolves.

The durable artifact is a semantic contract in patch.md; the code diff is one verified realization against one upstream commit.

See SPEC.md for the v0.1 design.

Current prototype

The repository contains:

• A Go patchmd CLI for deterministic state, validation, Git isolation, proposals, composition, and reapply preparation.
• A capture-patch-intent skill for incremental intent capture.
• A reapply-patch-intent skill for semantic adaptation and verification.
• Machine-readable schemas for the structured portions of the artifacts.
• Integration tests using temporary historical Git repositories.

The prototype prepares reapplication candidates but deliberately does not claim success until an agent or human completes the declared verification and records an outcome.

Build and test

go build ./cmd/patchmd
go test ./...

To install from a local checkout:

go install ./cmd/patchmd

Quick start

Initialize a Git repository after choosing the upstream ref to track:

patchmd init --upstream https://github.com/example/project.git --ref upstream/main
git add .patchmd.yaml .gitignore
git commit -m "Initialize Patch.md"

Explicitly begin capturing a persistent change:

patchmd begin disable-telemetry \
  --session telemetry-implementation \
  --author "Example Author" \
  --license MIT \
  --worktree

The capture skill incrementally edits the branch-local patch.md. At semantic checkpoints it runs:

patchmd checkpoint --session telemetry-implementation \
  --summary "Crash reporting is included; update checks are excluded"

After implementation and verification:

patchmd reference disable-telemetry
patchmd validate disable-telemetry --ready
patchmd ready disable-telemetry

To prepare the patch against a newer upstream revision:

patchmd reapply disable-telemetry \
  --to upstream/main \
  --session telemetry-upgrade

This creates an isolated worktree. A candidate result means the reference diff applied but verification is still pending. adaptation-required hands control to the reapply skill.

Composition

Create and resolve a patch set:

patchmd new-set private-deployment \
  disable-telemetry local-auth filesystem-storage \
  --intent "Run without vendor-hosted services"

patchmd compose private-deployment

Composition validates ready members, rejects missing dependencies, cycles, and declared conflicts, and emits deterministic dependency order plus capability warnings. Verification still runs against the cumulative result.

Concurrent sessions

Give every agent a unique session, branch, and worktree. Sessions checkpoint independently and produce commit-backed proposals:

patchmd propose \
  --session telemetry-acceptance \
  --summary "Add independent network-boundary acceptance tests" \
  --evidence acceptance=passed

Integration verifies the proposal's canonical base revision before cherry-picking it. A stale revision is a semantic conflict, not a last-write-wins update.

Trust boundary

Patch repositories and acceptance commands are untrusted input. The v0.1 CLI isolates Git work but does not yet provide an OS sandbox. Do not expose secrets or execute undeclared verification commands without review.