Metadata-Version: 2.4
Name: agent-ledger-harness
Version: 0.10.0
Summary: Deterministic Obsidian Markdown and Git-backed personal work ledger
Project-URL: Homepage, https://github.com/likaihz/tz-agent-harness
Project-URL: Repository, https://github.com/likaihz/tz-agent-harness
Project-URL: Issues, https://github.com/likaihz/tz-agent-harness/issues
Maintainer: litiezhu
License-Expression: MIT
License-File: LICENSE
Keywords: agent,cli,git,obsidian,work-tracking
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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

```text
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. Vault schema 4 remains unchanged.

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 and Vault schema 4 remains unchanged.

## Build

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

```text
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:

```text
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](https://github.com/likaihz/tz-agent-harness/blob/main/docs/pypi-release.md).

## Installation

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

```text
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.
