Motus

Motus is a local event-backed work ledger with a reference CLI. It records work as Store runs and append-only events, then derives packets, evidence, decisions, and receipts as projections you can trust later.

What Motus Solves

Important work usually disappears into chat, tickets, logs, and memory. That makes it hard to answer basic questions later:

• What was the work?
• Who owned it?
• What proof exists?
• What was accepted?
• What should happen next?

Motus makes those answers durable.

It records work as a Store run, appends useful events, and projects those facts into operator-facing packets, evidence, decisions, and receipts. Existing motus work commands remain as compatibility custody commands, but the default first-run path is the Store-backed motus wrap adapter. Store runs and append-only events are the deepest durable truth. Optional locks are for protected mutable resources, not the primary meaning of work.

Motus is useful with one person in one environment. It is also composable across environments that share the packet format. Neither mode requires the other.

The practical asymmetry is simple: if reconstructing a handoff costs more than recording it once, Motus is worth using.

What Motus Is

Motus defines the local work-truth surfaces that a work loop depends on:

1. records work as a bounded Store run,
2. appends structured proof while the work happens,
3. closes the run with an explicit outcome,
4. derives receipts and packets from durable facts,
5. preserves the result as deterministic lineage.

The shipped CLI is the reference implementation. Motus should not require a second implementation to be useful, but the kernel boundary is kept small enough that another implementation could preserve the same run, event, projection, and receipt truth.

Framework Portability

The reference CLI proves the local Store path. The framework layer proves that other systems can emit Motus-compatible receipts without importing the CLI.

Start with:

• Work Ledger RFC v0.1
• Work Receipt Envelope v0.1
• JSON schemas
• Semantic conventions
• Semantic convention schema mapping
• Conformance fixtures and validator

The framework surface in spec/, schemas/, semconv/, and conformance/ is copied from the canonical motus-work-ledger repository and pinned by MOTUS_WORK_LEDGER.lock.json. The CLI release gates fail if that copied surface drifts from the lock without an explicit resync.

This is intentionally narrower than a standard. A system can claim early Motus compatibility only by producing a receipt that validates against the schemas and fixtures for its claimed conformance level.

What Motus Is Not

Motus is not:

1. a replacement for Git, CI, ticketing, or your runtime,
2. a scheduler or orchestration product,
3. a hosted control tower,
4. a chat transcript archive.

Those systems still run work. Motus defines how work becomes reviewable, receiptable, and reusable.

Good First Use Cases

Start where reconstruction is already painful:

• AI-assisted code changes that need evidence and reviewable closeout,
• release decisions that need explicit scope, verification, and approval,
• CI validation handoffs where the next actor must inherit proof,
• exception approvals that need rationale, approver identity, and expiry,
• review or approval workflows where the accepted outcome must stay durable.

Do not start by trying to model every task, every transcript, or every agent memory surface. Start with one workflow where losing the contract, custody, evidence, or accepted outcome is already expensive.

Start Light With The Store

When command execution is the useful evidence, start with the Store-backed motus wrap adapter. It records one Store run and terminal outcome without manual evidence authoring.

When you need claim/evidence/release ergonomics, the compatibility work loop keeps that command shape. It writes a project-local Store run/event record by default while preserving the lease ID as a compatibility custody alias:

motus work claim ...
motus work evidence ...
motus work release ...

Set MOTUS_KERNEL_STORE_PATH or its compatibility alias MOTUS_STORE_PATH only when you need to override the default .motus/kernel-store.db location. If both are set, MOTUS_KERNEL_STORE_PATH wins. Set MOTUS_WORK_STORE_BRIDGE=disabled only for compatibility recovery; normal work should leave the bridge in auto mode.

Use userland governed patterns only when the consequence of the work justifies extra structure. Typical reasons:

• another actor must inherit the evidence and decision,
• the work changes a release, approval, or policy boundary,
• the closeout needs a stricter final receipt than the light loop provides.

Auto-Capture: Wrap A Command

When the useful evidence is command execution, use the Store-backed adapter instead of hand-authoring output evidence:

motus wrap -- pytest

motus wrap runs the command normally, streams stdout/stderr back to your terminal, and records one Store run with start, metadata-only output, and terminal outcome events. Raw stdout/stderr content is not persisted by default; the Store payload records byte counts, line counts, truncation state, and the terminal outcome. It is an adapter over the Store, not a workflow engine or scheduler.

GitHub Actions

Use the GitHub Action when CI command evidence should produce the same Store truth and receipt projection:

- uses: motus-os/motus@v0.5.3
  with:
    command: "pytest"
    export-path: "motus-run-export.json"
    receipt-path: "motus-receipt.json"

The Action writes a Store run, a deterministic Store export, and a receipt projection. Upload those files with your normal artifact policy if another reviewer or job needs them. Use if: always() on the artifact upload step if you want receipts from failing commands. The Action is a thin adapter over the Store path; it does not own workflow routing, approvals, or orchestration.

Install

pip install motusos
motus --help

Quickstart: First Store Run

motus doctor
motus wrap -- python3 -c "print('motus store run')"

This proves the Store-backed adapter path without hand-authoring evidence or using compatibility custody commands. motus doctor verifies Store health without creating a legacy coordination database; use motus doctor --fix only when you explicitly want it to initialize .motus/kernel-store.db.

Compatibility: Existing Work Loop

motus install
motus init --empty --path .
LEASE_ID=$(motus work claim ADHOC-QUICKSTART-001 --intent "First local work item" --json | python3 -c 'import json,sys; print(json.load(sys.stdin)["lease_id"])')
motus work evidence "$LEASE_ID" test_result --passed 1 --failed 0
motus work release "$LEASE_ID" success
motus work receipt "$LEASE_ID"

The compatibility loop is for users who need the established claim/evidence/ release command shape. It records linked Store run/event truth by default in .motus/kernel-store.db, but the lease_id is custody metadata rather than the durable kernel identity.

PowerShell:

$LEASE_ID = (motus work claim ADHOC-QUICKSTART-001 --intent "First local work item" --json | ConvertFrom-Json).lease_id
motus work evidence $LEASE_ID test_result --passed 1 --failed 0
motus work release $LEASE_ID success
motus work receipt $LEASE_ID

The shell pipeline extracts the compatibility lease_id from JSON output so you can reuse it in the next commands. motus work release closes the linked Store run, and motus work receipt prefers the Store receipt projection when one exists.

What each command does:

• motus install applies local defaults Motus expects.
• motus init --empty --path . creates the minimum neutral workspace layout.
• motus work claim ... opens compatibility custody for one bounded work item.
• motus work evidence ... attaches proof to that active lease and appends a Store evidence event.
• motus work release ... closes the lease and closes the linked Store run.
• motus work receipt ... inspects the durable close record and prefers the Store receipt projection when one exists.
• success, failure, and partial close as released attempts.
• aborted and expired remain distinct terminal states rather than accepted closeout.

What success looks like:

• claim returns a lease_id.
• evidence succeeds against that lease.
• release returns a receipt_id.
• receipt shows the durable close record for that lease, or the Store receipt projection when the bridge is configured.

Core Ideas

• Store run: the kernel lifecycle container.
• Event: append-only durable fact recorded for a run.
• Work packet: operator-facing projection over a run and its events.
• Evidence: proof-bearing events and references.
• Receipt: deterministic close projection for accepted work.
• Lease: current compatibility custody for motus work; not the long-term kernel lifecycle primitive.
• Lock: optional fenced protection for Motus-controlled mutable resources.
• Adapter: CLI, wrapper, hook, CI, or MCP surface that writes through the Store path.

Runtime Boundary

Motus is intentionally runtime-agnostic.

You can use it with:

• local scripts,
• CI jobs,
• agent workflows,
• N8N or other orchestrators,
• your own server/runtime stack.

Motus owns the local run/event truth and deterministic projections. You choose the downstream execution stack.

Public Boundary

Motus keeps three public layers distinct:

• Core: the invariant Store path: runs, append-only events, event kinds, deterministic exports, receipt projections, and optional fenced locks.
• Adapters: runtime- or vendor-specific observation and integration surfaces, including the current motus work claim/evidence/release/receipt compatibility loop while existing users migrate.
• Userland: governed workspace conventions, release workflows, review packets, and operating opinions layered on top of the core loop.

The package is strongest when those boundaries stay explicit.

The 0.5 migration target makes that boundary smaller: Store runs and events are the durable kernel truth, while work packets, evidence lists, decisions, receipts, handoffs, and route summaries are deterministic projections over that truth. Existing motus work claim/evidence/release/receipt commands remain a compatibility path while new use starts with Store-backed adapters.

If you need governed workspace conventions, treat them as optional userland patterns after the Store path is already clear.

Start Here

1. Quickstart
2. First Real Workflow
3. Evidence and Receipts
4. Kernel Boundary
5. GitHub Actions
6. Docs Index

Links

• PyPI: https://pypi.org/project/motusos/
• GitHub: https://github.com/motus-os/motus
• Contributing: CONTRIBUTING.md
• Security Policy: SECURITY.md

License

Apache License 2.0. See LICENSE.