https://github.com/motus-os/motus-work-ledger
Workflow-neutral work ledger schemas, semantic conventions, conformance, and receipt validation for human, AI, CI, and tool-driven work.
https://github.com/motus-os/motus-work-ledger
ai-agents ci conformance developer-tools evidence local-first provenance semantic-conventions work-ledger work-receipts
Last synced: 18 days ago
JSON representation
Workflow-neutral work ledger schemas, semantic conventions, conformance, and receipt validation for human, AI, CI, and tool-driven work.
- Host: GitHub
- URL: https://github.com/motus-os/motus-work-ledger
- Owner: motus-os
- License: apache-2.0
- Created: 2026-05-15T15:28:13.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-15T18:29:41.000Z (2 months ago)
- Last Synced: 2026-05-15T19:25:49.515Z (2 months ago)
- Topics: ai-agents, ci, conformance, developer-tools, evidence, local-first, provenance, semantic-conventions, work-ledger, work-receipts
- Language: Python
- Size: 98.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Notice: NOTICE
Awesome Lists containing this project
README
# Motus Work Ledger
> Motus Work Ledger is a workflow-neutral model for consequential human, AI,
> CI, and tool-driven work. It records work as append-only events and produces
> verifiable Work Receipts.
This repository is the canonical portable surface for Motus-compatible Work
Receipts. It defines the model, schemas, semantic conventions, conformance
fixtures, validation rules, and examples that other systems can implement
without using the `/motus` reference CLI.
## Why Work Needs A Ledger
Important work is increasingly performed across pull requests, tickets, CI
logs, chat, agent transcripts, scripts, and human approvals. Later, a reviewer
needs direct answers:
1. What work was attempted?
2. Who or what performed it?
3. What evidence existed?
4. What outcome was claimed?
5. What was accepted?
6. What should happen next?
Motus Work Ledger gives those answers a common structure.
## Core Model
```text
Work Journal -> Work Ledger -> Work Receipt
```
- The **Work Journal** is the append-only event stream.
- The **Work Ledger** is the organized durable work truth.
- The **Work Receipt** is the portable proof object projected from that truth.
Workflow tools do the work. Control planes steer the work. Motus records the
work. Receipts prove the work.
## What This Repo Contains
- `spec/` - Work Ledger RFC, Work Receipt envelope, canonicalization, and conformance levels.
- `schemas/` - strict JSON schemas for receipts, events, runs, evidence, routes, and handoffs.
- `semconv/` - shared semantic attributes and schema mapping.
- `conformance/` - validator, fixtures, golden hashes, and independent implementations.
- `examples/` - receipt examples for human, AI, CI, and tool-driven work.
- `docs/` - technical review, implementation, privacy, terminology, and adoption guidance.
Useful starting points:
- [Technical Review Guide](docs/technical-review-guide.md)
- [Two-Repo Review Package](docs/two-repo-review-package.md)
- [Repo Map](docs/repo-map.md)
- [Terminology](docs/terminology.md)
- [Work Journal](spec/work-journal.md)
- [Privacy And Security](docs/privacy-and-security.md)
- [External Review Checklist](docs/external-review-package.md)
- [Controlled Design-Partner Pilot](docs/design-partner-pilot.md)
- [Design-Partner Pilot Runbook](docs/design-partner-runbook.md)
- [Versioning](VERSIONING.md)
- [Changelog](CHANGELOG.md)
- [Schema Registry](schemas/index.json)
## Five-Minute Validation
Install the validator dependency:
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r conformance/validator/requirements.txt
```
Validate the registry, conformance suite, and bundled examples:
```bash
python conformance/validator/check_schema_registry.py
python conformance/validator/check_semconv_schema_map.py
python conformance/validator/check_conformance.py
python conformance/validator/validate_receipt.py examples/*/receipt.json
```
Generate and validate a receipt from an implementation that does not import
`/motus`:
```bash
python conformance/implementations/receipt-only-python/emit_receipt.py \
--input conformance/implementations/receipt-only-python/input.example.json \
--output /tmp/motus-work-receipt.json
python conformance/validator/validate_receipt.py /tmp/motus-work-receipt.json
```
Generate and validate an event-backed receipt projection:
```bash
python conformance/implementations/event-backed-python/emit_from_events.py \
--input conformance/implementations/event-backed-python/input.example.json \
--output-dir /tmp/motus-work-ledger-event-backed
python conformance/validator/validate_receipt.py \
/tmp/motus-work-ledger-event-backed/receipt.json
```
## Relationship To `/motus`
`/motus` is the reference implementation. It provides the CLI, local Store
runtime, adapters, and compatibility paths that exercise this model.
This repository is the canonical portable model. Other systems can emit
Motus-compatible Work Receipts without importing or running `/motus`.
## Non-Goals
Motus Work Ledger is not:
1. a workflow engine,
2. an agent runtime,
3. a model router,
4. a hosted control tower,
5. a compliance product,
6. employee surveillance,
7. a blockchain,
8. a raw transcript archive.
Motus records consequential work facts, not worker activity streams.