@bosun-sh/logbook 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [2.0.0] — 2026-05-09
+
+### Breaking Changes
+
+- **Workspace layout** — canonical storage moves to `.logbook/storage/` (epics, stories, tasks, context-entries, external-links, sync-events, sync-conflicts). The old `tasks.jsonl` at the repo root is no longer written; run `workspace.init` to migrate.
+- **MCP tool IDs** — all tools now use lowercase dotted IDs. V1 snake_case names are gone: `list_tasks` → `task.list`, `create_task` → `task.create`, `update_task` → `task.update`, `edit_task` → `task.edit`, `current_task` → `task.current`.
+- **Wire format** — task fields renamed to camelCase (`definitionOfDone`, `inProgressSince`, `phaseModelOverrides`, etc.). V1 JSONL is incompatible; run `workspace.init` for automatic migration.
+- **Single v2 binary** — `logbook` now exposes both CLI commands and MCP stdio mode via `logbook mcp`.
+- **Hooks config format** — hooks require JSON `config.json` with an argv-array `command` field. YAML configs and shell-string commands are no longer valid.
+
+### Added
+
+- **Ohtools plugin registry** — all 38 tools registered through `@bosun-sh/ohtools` with enforced `LOWERCASE_DOTTED_ID` format, ≤ 100 tool limit, ≤ 2 KiB description bound.
+- **Epic and Story entities** — `epic.*` and `story.*` tools with cascade delete, hierarchy, and context attachments.
+- **Context entries** — `context.*` tools for reusable information attachments with topic indexing.
+- **Linear sync** — `sync.linear.pull`, `sync.linear.push`, `sync.linear.status` as a first-class plugin.
+- **DuckDB optional index** — in-memory DuckDB over canonical `.logbook/storage/*.jsonl` via `read_json_auto` (non-canonical, never mutates storage).
+- **Hook templates** — `review-spawn` and `need-info-notify` materialized from `src/workspace/hook-templates/` on `workspace.init`.
+- **V1 migration** — `workspace.init` automatically migrates `tasks.jsonl` to v2 layout via `migrateV1Workspace`.
+- **MCP stdio mode** — newline-delimited JSON-RPC 2.0 loop available through `logbook mcp`.
+
+### Removed
+
+- `src/cli/`, `src/mcp/`, `src/infra/`, `src/domain/` — v1-only source trees deleted.
+- `src/hook/hook-executor.ts` — replaced by v2 hook runner in `src/hook/run.ts`.
+- V1 sibling task files (`create-task.ts`, `current-task.ts`, etc.) — replaced by v2 verbs.
+- Repo-root `hooks/` — replaced by `src/workspace/hook-templates/`.
+
+---
+
+## [1.1.0] — 2026-04-06
+
+### Added
+
+- **CLI entry point (`logbook`)** — new `logbook` binary providing all MCP tool functionality via command line. Supports all commands: `create-task`, `list-tasks`, `current-task`, `update-task`, `edit-task`, `init`.
+- **Shared layer infrastructure** — `src/infra/layer.ts` extracts the Effect layer construction used by both CLI and MCP server, ensuring consistent behavior across presentation layers.
+- **Session management in CLI** — sessions are auto-generated and persisted to `.logbook-session`. If a session exists, it's reused; otherwise a new one is created.
+- **Detailed help output** — `--help` now includes comprehensive documentation for each command with required/optional arguments, examples, and lifecycle diagrams.
+- **Enhanced error messages** — errors include CLI-specific hints showing the correct command format (e.g., "Use: logbook update-task --id=... --new-status=...").
+- **`logbook init` documentation generation** — running `init` in a new project creates `AGENTS.md` and `CLAUDE.md` with CLI documentation:
+  - If neither exists → creates AGENTS.md and symlinks CLAUDE.md to it
+  - If only AGENTS.md exists → appends logbook docs
+  - If only CLAUDE.md exists → appends logbook docs
+- **`--force` flag for `logbook init`** — ensures both AGENTS.md and CLAUDE.md exist. Appends to existing files, creates/symlinks missing ones.
+
+### Changed
+
+- **MCP server refactored** — `src/mcp/server.ts` now uses the shared layer from `src/infra/layer.ts` instead of duplicating layer construction.
+- **Project documentation** — `.claude/CLAUDE.md` updated with CLI usage section.
+- **Package description** — updated to reflect CLI support.
+- **README updated** — added CLI usage section, updated install and configuration docs.
+
+---
+
+## [1.0.0] — 2026-03-31
+
+### Added
+
+- **Structured JSON logger** — new `Logger` abstraction emits JSON lines to stderr. All `console.warn` calls replaced with `logger.warn`. Controlled via `LOGBOOK_LOG_LEVEL` env var (`debug|info|warn|error`, default `warn`).
+- **Unrecognized hook key warnings** — `hook-config-loader` now warns via the structured logger when a `config.yml` contains keys outside the known schema, surfacing typos early.
+- **Project and milestone filters for `list_tasks`** — callers can now pass `project` and `milestone` query parameters to scope task listing without loading the full store.
+- **`logbook-mcp init` scaffold command** — running `logbook-mcp init` creates `tasks.jsonl`, the `hooks/` directory tree, and emits client config snippets for Claude Code and OpenCode.
+- **`--version` / `-v` flags** — prints the package version and exits.
+- **`--help` / `-h` flags** — prints command usage, available subcommands, and all environment variables.
+- **`quickstart.md`** — zero-to-running onboarding guide: install, init, wire into an MCP client, and verify the first task.
+- **README: install section** — `npm install -g @bosun-sh/logbook` command and link to `quickstart.md`.
+- **README: agent session walkthrough** — end-to-end narrative showing how an agent picks up a task, works through it, and closes the loop.
+- **README: API stability guarantees** — documents the stability contract: tools and their input/output shapes are stable within a major version; internal module paths are not part of the public API.
+
+### Changed
+
+- CLI entry point (`server.ts`) consolidates all pre-start flag handling (`init`, `--version`, `--help`) inside a single `handleCliFlags()` function for clarity.
+- Biome config excludes `.claude/` directory from linting/formatting scope.
+
+---
+
+## [0.4.0] — 2026-03-30
+
+### Added
+
+- **Priority-based task selection** — `Task` gains a `priority: number` field (integer ≥ 0, default 0). `current_task` resolves via a deterministic priority chain: own in_progress → unassigned in_progress → orphaned in_progress (dead-session assignee) → highest-priority todo (auto-transitioned) → `no_current_task` error. Within each step tasks are ordered by priority DESC, tie-broken by `in_progress_since` ASC.
+- **Session liveness tracking** — new `SessionRegistry` interface + `PidSessionRegistry` implementation tracks agent sessions via `process.kill(pid, 0)`. Dead-session tasks are automatically reclaimed by the next available agent.
+- **Orphan recovery** — tasks assigned to crashed sessions are detected and re-claimed rather than left stuck in `in_progress`.
+- **Classification-first reviewer flow** — reviewer agent now classifies all findings before acting: must-fix blocks shipping, consider lets the implementer decide, nice-to-have creates silent `[tech debt]` backlog tasks. Reviewer always closes its own review task.
+- **API docs + client setup** — README now documents all TypeScript contracts (`CommentInput`, `CreateTaskInput`, `EditTaskInput`) and includes setup snippets for Claude Code and OpenCode.
+
+### Changed
+
+- `assignee` field on `Task` is now optional — tasks may exist without an assignee until claimed.
+- `list_tasks` results are now sorted by `priority DESC`.
+- Agent instructions are injected into the MCP `initialize` response (model selection guidance based on `predictedKTokens`).
+
+---
+
+## [0.3.0] — 2026-03-30
+
+### Fixed
+
+- Propagate domain errors with correct error codes (-32001 to -32006) instead of generic -32603
+- Reply cycle in `update_task` now accessible via MCP interface (optional `id` and `reply` fields)
+- Fixed MCP configuration issues
+
+### Added
+
+- OpenCode integration (`opencode.json`)
+- Improved review flow with better error handling
+- New tests for error codes and reply cycle
+
+---
+
+## [0.2.0] — 2026-03-29 — Initial public release
+
+### Added
+
+- **MCP server** (`logbook-mcp`) with five tools: `list_tasks`, `current_task`, `update_task`, `create_task`, `edit_task`
+- **Task lifecycle** with seven statuses: `backlog → todo → in_progress → pending_review → done` (plus `need_info` and `blocked` side-channels)
+- **Hooks system** — declarative `config.yml` + script pairs that fire on `task.status_changed` events; supports any executable language
+- **Built-in hooks**:
+  - `need-info-notify` — notifies the user when a task moves to `need_info` with the blocking comment
+  - `review-spawn` — spawns a reviewer sub-agent and creates a `review-*` task when a task moves to `pending_review`
+  - Second-task guard — requires a justification comment before a second task can enter `in_progress`
+- **JSONL persistence** — one task per line, append-only writes; human-readable without tooling
+- **Session-scoped agents** — each MCP connection is a distinct agent; `current_task` is scoped to the calling session
+- **Effect.ts** typed error handling throughout; Zod validation at every MCP boundary
+- 100% test coverage (unit + E2E)
+
+### Package
+
+- Published as `logbook-mcp` on npm
+- Requires Bun ≥ 1.0.0
+- Two production dependencies: `effect`, `zod`