work-ledger

README

Motus Work Ledger

Motus records command runs in a local SQLite ledger. It keeps the command name, timing, Git state, output counts, exit status, and outcome without storing the command's arguments or raw output. When a run exposes something worth keeping, you can connect a short finding to it and later connect the fix to a successful run.

Terminal scrollback disappears and CI logs live in separate systems. Motus gives those runs one local index, searchable findings, and a deterministic JSON receipt you can read later.

Try it from source

Build the current source with Go 1.26.5:

$ go build -o ./bin/motus ./cmd/motus
$ ./bin/motus wrap -- go test ./...
ok      github.com/example/project  0.42s
motus: recorded run_7e2f... (success)
Next: ./bin/motus --state-dir /work/project/.motus run receipt run_7e2f...

Then list and inspect the record:

$ ./bin/motus run list
RUN ID      STATE   OUTCOME  STARTED (UTC)         COMMAND
run_7e2f... closed  success  2026-07-21T17:27:33Z  go

$ ./bin/motus run receipt run_7e2f... > receipt.json
$ ./bin/motus doctor
PASS  state path: state directory and database paths pass local safety checks
...
Scope: local consistency only; producer-controlled records are not independently authenticated.

If a run exposed a useful failure, record the finding through standard input. The text is read by Motus, not parsed as a command-line value. Type one line, then press Ctrl-D to finish:

$ ./bin/motus finding add --run run_7e2f... --file -
The retry reused stale generated state.
Recorded finding_91ac... (open)
Run: run_7e2f...
Summary: The retry reused stale generated state.

$ ./bin/motus finding list --state open
FINDING ID       STATE  RECORDED (UTC)         ORIGIN RUN   SUMMARY
finding_91ac...  open   2026-07-21T17:31:05Z  run_7e2f...  The retry reused stale generated state.

After a successful fix run, close the finding with finding close. Motus keeps the original finding and appends a separate closure instead of rewriting it.

motus wrap starts the command directly, without a shell. It forwards stdin and copies stdout and stderr to their original destinations. Motus records byte and newline counts observed before the command finishes or Motus terminates it. Because output is copied through pipes, a program that checks for a terminal can format its output differently than it would when run directly. If an output destination closes, Motus stops the command tree and records a failure.

What is recorded

• a random run ID and timestamps
• the executable's base name and argument count
• the Git repository name, commit, and pre-run dirty state when available
• stdout and stderr byte and newline counts
• exit code or terminating signal when available, and outcome
• canonical event payloads created by Motus
• finding summaries, hypotheses, next steps, and closure notes that you explicitly supply

Motus does not store command argument values, command stdin, raw stdout or stderr, environment variables, source files, prompts, or agent transcripts. Finding text is the exception: Motus stores the validated finding content you submit through a file or stdin. It does not send ledger data over the network.

State and commands

By default, Motus uses .motus/ledger.db at the current Git root. Outside a Git repository, it uses the current directory. Override this with --state-dir PATH or MOTUS_STATE_DIR.

Motus creates state directories with private POSIX permissions. If you create a custom state directory yourself, restrict it to the current user before use.

motus wrap -- COMMAND [ARG ...]  Run a command and record selected metadata
motus run list [OPTIONS]         List and filter recorded runs
motus run receipt RUN_ID         Write a JSON receipt for a closed run
motus finding add [OPTIONS]      Connect an authored finding to a run
motus finding list [OPTIONS]     List and search findings
motus finding show FINDING_ID    Show a finding and its run context
motus finding close [OPTIONS]    Resolve or dismiss a finding
motus doctor [--json]            Check local database consistency
motus version                    Print version information

Add .motus/ to the project's ignore file if the ledger should remain outside version control.

Trust boundary

A Motus receipt is a producer-controlled process record. Findings are also producer-controlled records: their text is authored, not independently verified or inferred by Motus. Database triggers block ordinary updates and deletes, and motus doctor checks the current schema, hashes, sequences, foreign keys, terminal records, and finding links. A person who controls the database file can replace those controls and rewrite a self-consistent history. Motus does not sign records, provide an independent observation, or prove that the recorded work was correct.

The receipt states this boundary as "trust_model":"producer-controlled". See SECURITY.md for the full security model and ARCHITECTURE.md for the data flow and storage design.

Development

The normal checks use standard Go commands:

$ go test -race ./...
$ go vet ./...
$ go build ./cmd/motus

The default pull-request workflow runs once on Ubuntu. Release builds run the suite natively on Ubuntu, macOS, and Windows first; the same native check can also be started manually.

See CONTRIBUTING.md before proposing a change.

License

Apache License 2.0. See LICENSE. Binary archives also include the applicable third-party notices.