motusos 0.4.10

Local event-backed work ledger with Store runs, append-only events, receipts, and projections

Motus CLI

The Motus CLI is the reference local interface for the Store-backed work ledger. The local Store records durable run/event facts; work packets, evidence, decisions, and receipts are projections over those facts.

1. start or observe a bounded run,
2. record append-only events,
3. close with a terminal outcome,
4. inspect packet and receipt projections,
5. keep compatibility work loops available while the Store path matures.

Install

pip install motusos
motus --help

First Store Loop

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

What this proves:

• the CLI can execute an observed command,
• the Store records run and outcome events,
• output is summarized as metadata rather than persisted as raw transcript,
• the command path is adapter-backed rather than manually journaled.

Compatibility Work Loop

motus install
motus init --empty --path .
motus doctor
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"

What this proves:

• the CLI is installed,
• the local workspace is initialized,
• a work item can be claimed through the compatibility lease path,
• evidence can be attached,
• a terminal receipt can be emitted and inspected directly,
• the same loop writes project-local Store run/event truth by default and receipt reads prefer the Store projection.

Light Path Vs Governed Path

Use the light path for routine bounded work:

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

The compatibility loop creates or uses .motus/kernel-store.db by default. Set MOTUS_KERNEL_STORE_PATH or MOTUS_STORE_PATH only when you need a different Store path. Set MOTUS_WORK_STORE_BRIDGE=disabled only for explicit compatibility recovery.

Use the governed packet path only when the consequence of the work justifies the extra structure, for example:

• a release decision needs explicit scope, review, and closeout,
• another actor must inherit the proof and acceptance boundary,
• the work needs a stricter final receipt than the light loop provides.

Reference Release Workflow

Motus also includes a bounded compiled release workflow example for consequential release work. It is userland over the work ledger, not a hidden orchestration engine:

motus release scaffold --release-id 0.4.0
motus release sync --release-id 0.4.0
motus release validate --release-id 0.4.0
motus release finalize --release-id 0.4.0

When running from the source tree instead of an installed CLI, bind to the repo package explicitly:

PYTHONPATH=src python3 -m motus.cli release scaffold --release-id 0.4.0
PYTHONPATH=src python3 -m motus.cli release sync --release-id 0.4.0
PYTHONPATH=src python3 -m motus.cli release validate --release-id 0.4.0
PYTHONPATH=src python3 -m motus.cli release finalize --release-id 0.4.0

That workflow forms the release as explicit work:

• one authored release-source.json,
• one generated workflow manifest,
• six generated stage packets,
• one generated receipt template,
• one generated metrics template,
• one strict final-receipt.json.

Workspace layout:

.motus/releases/{release-id}/
  release-source.json
  generated/
    workflow.json
    packets/*.json
    receipt-template.json
    metrics-template.json
  final-receipt.json

Rules:

• release_id must be a slug using only letters, digits, ., _, or -.
• release-source.json is the only authored release-instance surface.
• generated outputs are disposable and are rebuilt by sync.
• validate is no-write and fails closed on drift.
• finalize emits one immutable final receipt.

The packets route to capability classes and keep runtime-brand decisions behind the adapter boundary.

Read Next

• Operator Guide
• First Real Workflow
• Evidence and Receipts
• Using the Work Ledger
• Release Workflow Tutorial
• Release Workflow Reference
• Architecture
• Kernel RFC
• CLI Reference
• Docs Index