agent-ledger-harness

Work Ledger CLI

work-ledger is a deterministic command-line tool for managing an Obsidian-compatible, Git-backed personal work ledger. It owns IDs, schemas, links, locking, transactions, Git commits, privacy filtering, weekly-report facts, diagnostics, and migrations.

Requirements

• Python 3.11 or newer
• Git
• A POSIX platform providing fcntl.flock (macOS or Linux)

The runtime uses only the Python standard library.

Entry points

work-ledger --version
work-ledger version
work-ledger capabilities
python -m work_ledger

All commands except --version emit exactly one JSON object on stdout. Run work-ledger --help for the complete command surface.

Configuration defaults to ~/.config/work-ledger/config.toml; local state defaults to ~/.local/state/work-ledger/. Override them with WORK_LEDGER_CONFIG and WORK_LEDGER_STATE_DIR for isolated environments.

Projects support nullable ISO start_date and end_date boundaries. When both are present, the start must be on or before the end. The range is descriptive and does not automatically change project status or reject tasks and events outside it.

Project and Task notes use a portable projection of the creation title as their permanent readable filename. Their titles are immutable, and projected filenames are unique within each note type. In schema 4, a root Task stores its Project link while a child Task stores only its parent link and derives project membership recursively, keeping the Obsidian Graph free of redundant child-to-project edges. CLI 0.6 and later migrate schema 1, 2, or 3 Vaults to schema 4 in one Git-backed transaction and reject ambiguous cross-project child histories.

CLI 0.7 adds work-ledger snapshot, a body-free, deterministic read projection for desktop visualization clients. It returns Project, Task, effective Event and weekly Report summaries from one shared read lock, including the derived project for child tasks, Vault identity, managed Work digest and an independent snapshot schema version.

CLI 0.8 adds work-ledger report export, a read-only clean projection of a digest-valid managed Report. Markdown export removes controlled frontmatter and evidence comments and reduces Obsidian wikilinks to visible labels; text export also removes Markdown presentation syntax. Export requires an explicit personal or reportable audience and never writes the Vault or Git history.

CLI 0.9 enriches work-ledger report facts with visibility-filtered Project and Task bodies plus the ancestor Task context needed to synthesize workstreams. Report evidence validation also covers full-width and ASCII numbered paragraphs used by paste-ready weekly reports. That release retained Vault schema 4.

CLI 0.10 makes a newly created ordinary Project reportable when visibility is omitted. Explicit private remains supported, Task and Event visibility still copies the current effective visibility of its parent at creation, and the protected Inbox remains private. Existing Vault objects are not rewritten; that release retained Vault schema 4.

Knowledge documents in Vault schema 6

Events are append-only, project-linked evidence: use idea or insight when the fact itself is the durable record. Knowledge is a mutable synthesis at Work/Knowledge/<immutable-slug>.md; it may cite origin Events and optionally a Project, but it never replaces or rewrites Journal evidence. The CLI supports knowledge.create, knowledge.update, knowledge list, knowledge show, resolve --type knowledge, Event backlinks, Snapshot projection and digest coverage, visibility closure, and Knowledge-aware doctor findings.

Vault schema 6 adds the document kind for structured project artifacts kept for durable reference or maintenance. Existing research, comparison, technical_note, essay, and note semantics remain unchanged. The explicit schema 5 to 6 migration changes only the Vault marker and preserves existing Knowledge bytes.

Vault schema 7 adds the memo kind for maintained personal facts and inventories, such as cloud resources, subscriptions, domains, licenses, and warranty records. It is not a task queue, project specification, or secrets store. The schema 6 to 7 migration is marker-only and preserves all existing Knowledge bytes.

A schema 7 init creates the managed Knowledge sentinel. The historical explicit schema 4 to 5 migration still refuses to claim any pre-existing Markdown in Work/Knowledge/; schema 5 then migrates through 6 and 7 without rewriting those documents.

CLI 0.11.0 remains the supported compatibility baseline; runtimes implementing Vault schema 7 advertise knowledge_kind_document=true and knowledge_kind_memo=true. Protocol version 1 and apply request schema 1 remain unchanged, while Snapshot schema advances to 3. The release controller owns __version__, generated .release/*.json, and the Changelog; product changes do not edit those release outputs by hand.

Build

Any PEP 517 frontend can build the standard artifacts. For example:

uv build --out-dir dist
python tools/build_zipapp.py --dist dist

The first command builds the wheel and sdist. The second builds an executable zipapp and writes SHA256SUMS for all artifacts.

For the complete PyPI release gate, install build and twine, then run:

python tools/build_pypi.py --dist dist

The helper runs the source test suite, builds exactly one wheel and one sdist, runs twine check, validates and installs the direct wheel, rebuilds a wheel from the sdist in an isolated PEP 517 environment, and subjects that rebuilt wheel to the same metadata, installation, and CLI probes.

Public distribution

Production wheel and source-distribution releases use the agent-ledger-harness distribution name on PyPI. They are published through GitHub Actions Trusted Publishing after TestPyPI installation verification and the merged CLI Release PR approval. The executable zipapp and SHA256SUMS are attached to the matching GitHub Release.

Published versions are immutable and follow PEP 440. The version in src/work_ledger/__init__.py is the source for package metadata, CLI probes, tags, and artifact names. See the public PyPI release runbook.

Installation

Install an exact production version with a user-level tool manager such as pipx or uv tool:

pipx install agent-ledger-harness==<version>
uv tool install agent-ledger-harness==<version>

These installs provide the work-ledger command and work_ledger Python module for the work-ledger-cli product. A verified wheel or GitHub Release zipapp is also supported. Never make normal or scheduled use depend on TestPyPI, an editable checkout, or an unfixed latest version.

GitHub Release zipapps are bare .pyz files, and HTTP downloads do not preserve POSIX file modes. Verify SHA256SUMS, then run one portably with python3 work-ledger-<version>.pyz. On POSIX, after checksum verification, chmod +x work-ledger-<version>.pyz also enables direct execution.