Skip to main content

74. Git as Atomic Engine for Tasks

Status: Accepted Date: 2025-07-06

Context​

We need a task management system, michi, primarily for a solo developer working with an AI agent. The system needs to be simple, robust, and have zero operational overhead. Traditional solutions require a database server, an application server, and an API. This adds complexity (setup, maintenance, backups) that is unnecessary for this single-agent workflow. We need a way to perform atomic state changes (e.g., creating or completing a task) without a traditional backend.

Decision​

The michi system will use Git itself as its transactional engine. All state changes to tasks will be performed as atomic Git commits. There will be no separate database or API server.

The workflow for any task operation (e.g., michi:add) will be:

  1. Pull: The script will first run git pull --rebase to ensure it has the latest state.
  2. Lock: It will acquire a file-based lock to prevent concurrent operations (adr://lock-based-concurrency).
  3. Mutate: The script will perform the file system operations (e.g., creating a new JSON file for a task, as per adr://file-based-storage).
  4. Commit: It will git add the changes and create a single, atomic commit with a structured message (e.g., michi:add --title="New Task").
  5. Push: The script will immediately git push the commit to the remote repository.
  6. Unlock: It will release the lock.

This makes every task operation a durable, auditable, and atomic transaction recorded in the Git history.

Consequences​

Positive:

  • Zero Operational Overhead: Eliminates the need for any database or application servers, backups, or network configuration. The entire system lives within the Git repository.
  • Perfect Audit Trail: The Git history becomes a perfect, immutable log of every single change made to the task list.
  • Natural Distribution & Consensus: Git's distributed nature provides a natural mechanism for consensus. The state of the remote repository is the single source of truth.
  • Offline Capability: Operations can be performed and committed locally even without a network connection, and then pushed later.
  • Simplicity: The implementation relies on simple, universally available tools (Git and shell scripts).

Negative:

  • Unconventional: This is a highly unconventional use of Git and may be confusing to developers accustomed to traditional client-server architectures.
  • Potential for Conflicts: If two agents (or an agent and a human) operate on the same branch concurrently, it can lead to Git merge/rebase conflicts that require manual intervention.
  • Performance at Scale: This pattern is not designed for high-frequency, multi-user collaboration. A large number of small commits could bloat the repository over time, though this is unlikely in the intended single-agent workflow.

Mitigation:

  • Single-Agent Focus: The system is explicitly designed for a single developer and their AI assistant. The risk of concurrent conflicts is low and manageable.
  • Clear Conflict Resolution Path: The michi scripts will be designed to detect push/pull failures and provide clear instructions for manual conflict resolution when it occurs.
  • Shallow Clones/History Pruning: For very long-running projects, Git's features for managing history size (like shallow clones) can be used if repository bloat ever becomes a concern.
  • Clear Documentation: This core architectural decision will be heavily documented so its unconventional nature is well understood by anyone working on the project.