@rundiffusion/ledger

rdt is a Git-native engineering task, claim, delivery, and accountability CLI. It stores no company data outside the repository that invokes it:

• Markdown on the default branch is the durable task and shiplog ledger.
• remote Git refs arbitrate active claims and pin handoffs;
• Git history records authorship and evidence;
• repository CI decides what may merge.

There is no database, hosted service, daemon, telemetry, HTTP client, or persistent cache. Any JSON audit output is a disposable CI artifact.

Develop

Use Node 22.15 or newer:

npm ci
npm test

The integration suite creates temporary bare Git remotes and proves claim races, exact-SHA leases, immutable handoffs, safe claim cleanup, and delivery accountability. Destructive tests never use a consumer repository's remote.

To exercise the CLI from a repository containing accountability.config.json:

npm run build
node /path/to/devapps/ledger/dist/cli.js check

Package safety

Before publishing, run:

npm ci
npm test
npm pack --dry-run --json

The package files allowlist permits only dist/, this README, and the MIT license. Inspect the dry-run JSON and reject the release if it includes tests, fixtures, credentials, repository configuration, tasks, shiplogs, or plans.

The runtime dependency list intentionally contains only the generic YAML parser. Do not add network clients, database drivers, telemetry, or caches.

Safe claim cleanup

rdt cleanup [TASK-ID] is always a dry run. It must run from a clean local default branch whose HEAD exactly matches the fetched remote default branch. Only work/<ID> refs whose Markdown proves an implementation merge are eligible. rdt cleanup [TASK-ID] --apply then:

1. archives the exact inspected tip under archive/work/<ID>/cleanup-...;
2. deletes the remote claim with an exact-SHA lease; and
3. removes only a matching clean local worktree and branch.

Dirty or divergent local work blocks cleanup. handoff/ refs and existing archive/ refs are never deleted. Agents should show the dry-run result and use --apply only when a developer explicitly requests the mutation.

Manual release

The canonical source remains in the private image-ai Bitbucket repository, so releases use a manual public npm publish rather than public-GitHub OIDC:

npm login
npm publish --access public --otp <current-2fa-code>

Never commit an npm token. Publish from a clean commit, with npm 2FA enabled, after reviewing npm pack --dry-run --json. Consumer repositories exact-pin the published version in their lockfiles.

Repository contract

Each consumer supplies accountability.config.json, tasks/, shiplog/, and plans/. Run rdt --help for the public commands. Daily operating guidance belongs in the consuming repository's docs/agents/engineering-ledger.md so that humans and agents see the same policy beside the code.