Ledger-CLI v2 — implementation notes (ID-35 close-out)

Ledger-CLI v2 — implementation notes (ID-35 close-out)

Short close-out notes for the ID-35 ledger-CLI v2 wave. The authoritative spec is RESEARCH.md (and PLAN.md for the subtask breakdown); this file records only what a future reader needs to know that is NOT obvious from the code.

What shipped

The v2 CLI (scripts/ledger-cli.ts) over the vendored lib/ledger/ primitives now covers the full surface — read (show / get / schema), status flips and field edits (flip-task / flip-subtask / update-task / update-subtask / update-roadmap / update-backlog / append-journal), record create (add-subtask / open-task / create-theme / create-backlog), delete-backlog, and the cross-ledger promote — with two prevent-at-source write gates (record-set preservation {35.16} + write-time budget {35.17}, --force escape hatch), three input modes (positional JSON / --file+stdin / named flags) with auto-id, default-on mirror regen ({35.18}), and the discoverability surface ({35.22}). See the in-file USAGE block and lib/ledger/README.md for the operator reference, and docs/reference/task-list-discipline.md §2/§3 for field discipline (now reflecting the write-time hard-reject behaviour).

Backlog title mirror rendering — deferred to a future ID-20 fork release

The schema-side win is complete: BacklogItemSchema carries an optional title ({35.14}), the live backlog is backfilled across all 149 items ({35.23}), the CLI surfaces title (create-backlog --title …, update-backlog <id> title …, schema backlog), and the write-time budget gate enforces title ≤ 80.

However, the task-view mirror still renders the backlog item description (not title) as the N.md H1. Rendering title as the H1 (with description as the sub-line) is done by task-view’s mirror-generator.ts, which is not vendored here and is regenerated by regen-mirrors.sh cloning task-view at the pinned TASK_VIEW_TAG. That renderer change requires a future task-view fork release — ID-20 owns the fork and works it in parallel; this wave does NOT edit it. Until that fork release ships and TASK_VIEW_TAG is bumped, the canonical JSON carries title and the CLI surfaces it, but the rendered mirror H1 keeps showing description.

Spec of record: RESEARCH.md §6.3 (“Mirror rendering — OUT OF SCOPE for this wave (task-view fork)”); see also §6.1 (field shape) and PLAN.md ({35.14}).