[Ranjithsingh2004]

What

A new bundled skill: reading-list — a durable per-workspace ledger for books, papers, and articles.

The ledger is a single JSON file at <cwd>/reading/reading.json, so it lives in the workspace and travels with it (diffable, committable) rather than in an opaque database.

add <title> [--author A] [--kind book|paper|article] [--pages N] [--tags a,b] [--url U]
list [--status want|reading|finished] [--tag T]      show <id>
start <id> [--page N]                                progress <id> <page>
finish <id> [--rating 1-5]                           rate <id> <1-5>
note <id> <text>                                     remove <id> --yes
stats [--json]

It complements habit-tracker (recurring routines) and expense-split (money): a book is read once, front to back, so it has a start, a finish, and a page count that only ever goes up.

Invariants (promised in SKILL.md, pinned in tests)

• Honest progress — a page past the end of a known-length item is refused, and mid-book progress never marks it finished; it auto-finishes only at the last page.
• Exact id beats a partial match, and an ambiguous fragment is refused with the candidates listed instead of guessed at.
• remove needs --yes and the refused removal never lands.
• Atomic writes — temp file + rename, with no leftover temp files.
• A corrupt/malformed ledger is refused (exit 2) and left untouched rather than silently overwritten. The whole point of a reading history is that it survives a bad parse.

Exit codes: 0 ok · 1 usage/refused · 2 corrupt ledger.

Tests

bundled-reading-list.test.ts (9/9 pass) spawns the shipped script in a throwaway workspace and covers: discoverability as a bundled skill, progress/finish semantics, the past-the-end refusal, exact-id vs ambiguous fragment, --yes on remove, no temp leftovers, corrupt-ledger refusal without mutation, list filtering, and stats --json.

npm run typecheck clean.