motusos 0.6.0

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 Userland

Use the light path for routine bounded command evidence:

motus wrap -- pytest

Use the compatibility work loop only when you need claim/evidence/release ergonomics:

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

Both paths create or use .motus/kernel-store.db by default. Set MOTUS_KERNEL_STORE_PATH or its compatibility alias MOTUS_STORE_PATH only when you need a different Store path. If both are set, MOTUS_KERNEL_STORE_PATH wins. Set MOTUS_WORK_STORE_BRIDGE=disabled only for explicit compatibility recovery.

Inspect Work Records

Use motus insights self-audit when you want a deterministic diagnostic report over local work records and repository artifacts:

motus insights self-audit --json

The command uses file scans and SQL only. It reports bounded findings such as closure gaps, missing handoff reasons, repeated failure patterns, and process/product imbalance. Default JSON redacts input paths and work-item titles. It does not create facts with a model and does not route work.

Add userland process only when the consequence of the work justifies 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.

Those higher-order workflows should reference Store runs, evidence, decisions, and receipt projections. They should not become a second Store or a hidden orchestration engine.

Framework Portability

The CLI is the reference implementation. The portable framework surface lives in the repository-level spec/, schemas/, semconv/, and conformance/ directories. Those artifacts define the draft Work Receipt Envelope, shared semantic attribute names, and receipt-only conformance fixtures for systems that want to emit Motus-compatible receipts without importing motusos.

Read Next

• Operator Guide
• First Real Workflow
• Evidence and Receipts
• Using the Work Ledger
• Architecture
• Kernel RFC
• Work Ledger RFC
• Semantic Conventions
• Semantic Convention Schema Mapping
• CLI Reference
• Docs Index