p-backlog 0.2.3 → 0.3.0

package/CHANGELOG.md

@@ -1,10 +1,60 @@
 # Changelog
 
+## 0.3.0
+
+CLI contract changes (scripts that parse output or exit codes may need updating):
+
+- `take --path --json` prints a single JSON array instead of several JSON objects separated by `---`.
+- `new --json` prints the same task object as `show --json` and `take --json` (with progress, blockers and links) instead of the raw stored task.
+- `deletesAt` in `--json` output is a local ISO time with offset, like `created` and `closed`, instead of UTC.
+- `check` exits with `5` only when there are candidates or task problems; project setup problems (no repos, missing repo, shared prefix) are reported with exit code `0`.
+- `service` on a system without autostart support exits with `4` (the command failed) instead of `3` (refused).
+- `backlog`, `backlog --help` and `backlog <command> --help` print help to stdout with exit code `0`.
+- Argument errors are shown in the interface language and followed by the command's usage. Arguments that used to be ignored are now rejected with exit code `1`: extra words after `project list`, `--confirm` outside `project delete`, an empty `list --status`, `take <ID> --project`, `take --next|--path --force`, a `serve --port` that is not a decimal number from 1 to 65535.
+- `serve` and `service install` reject a `PORT` environment variable that is not a decimal number from 1 to 65535 with exit code `1` instead of silently using 4317. `serve` exits with `0` after a clean stop on SIGTERM, SIGINT or SIGHUP.
+- `stats` prints warnings about unparsed task files and journal lines before the "Open" line; `stats --json` has `unparsedTasks` and `invalidJournalLines`. `totals.open`, the age median and the open weight now count tasks by their history, so an open task whose file cannot be parsed is still counted. `forecast.windowWeeks` is replaced by `forecast.windowDays` — the span the weekly rate is computed over.
+- `stats --json` also has `unknownJournalLines`, and `stats` prints a matching warning. A journal line with a renamed or otherwise unrecognized category, "how found" or resolution value is now read as `unknown` and kept in the quality breakdowns (its own row or `byReason.unknown`) instead of silently dropping out.
+- `hook stop` exits with `0` on internal failures (for example, an unreadable backlog directory) and only prints a warning to stderr, so Claude Code on Windows no longer reports a hook error on every turn.
+
+Other changes:
+
+- `setup` writes `~/.claude/settings.json` atomically, keeps its key order and file mode, and writes through a symlink (including a dangling one) instead of replacing it.
+- Windows service: `service install|uninstall` stops the process from `server.pid` only after checking that it is this p-backlog server; if the check is impossible, the PID file is kept and a warning is printed.
+- The CLI trims `.runs.jsonl` by itself, so the run log no longer grows without the web server.
+- `dist/server.js` is no longer shipped in the npm package.
+- The server stops cleanly on SIGTERM, SIGINT and SIGHUP: it finishes edits already in progress, closes open browser tabs' event streams and removes its PID file, instead of being killed mid-write.
+- The web UI cannot be embedded in another site's frame (`X-Frame-Options: DENY`, CSP `frame-ancestors 'none'`). The CSP loads scripts, styles and images only from the server itself (images also from `data:`), so an external image in a task description is not shown: text written by an agent cannot make the browser contact a third-party host.
+- A file locked by another process for more than 5 seconds is reported by the API as `503` with an explanation instead of `500`.
+
+Fixes:
+
+- Re-check: the symbol filter looks the task's symbol up at the task's current line, so a candidate is no longer
+  dropped (and the anchor re-attached to a neighbouring function) when lines above the task moved.
+- Re-check: edits that arrive with a merge commit are seen; the diff base follows the first parent; a user's external
+  diff tool or `diff.suppressBlankEmpty` no longer breaks hunk parsing; `git log` is limited to the tasks' paths, and a
+  git failure is reported instead of silently producing no candidates.
+- Re-check: `verify` clears the anchor when the task's line is past the end of the file, and moves `source` to the
+  task's current place when the lines shifted.
+- Task numbers of deleted tasks are never reused, even when `backlog new` races with the cleanup.
+- An unparseable `project.md` no longer makes `backlog new` create a second project with the same prefix.
+- Git worktrees belong to the main repository's project; the hook and checks see commits made in the worktree.
+- The Stop hook remembers what it already told each session separately, so parallel sessions don't repeat each other.
+- Statistics: a task whose file can't be parsed keeps its last status instead of an invented "cancelled"; the open
+  count, forecast and debt curve use one history; model prices are matched by exact id (`claude-opus-5-5` added);
+  fixes are dated by when they landed on the main branch.
+- Web UI: a focused field no longer overwrites an edit made by the agent meanwhile (a conflict is shown instead); a
+  failed background refresh no longer wipes the page and the description draft; errors are shown in the interface
+  language; all tabs share one live-update connection, so many open tabs no longer stall.
+
+## 0.2.4
+
+- A clearer description on npm and GitHub, and a rewritten README introduction: out-of-scope fixes stay out of pull requests, audit findings don't get lost, tasks keep the context the agent needs. No code changes.
+
 ## 0.2.3
 
 - README: screenshots of the task list, a task card and statistics (English UI in README.md, Russian UI in README.ru.md), generated from fictional demo data with `npm run screenshots`. No code changes.
 
-## 0.2.2 (not published to npm; its changes ship in 0.2.3)
+## 0.2.2
 
 - README: npm, CI, Node and license badges; a section on using p-backlog together with code-review-graph (re-check by symbol). No code changes.
 

package/README.md

@@ -4,14 +4,28 @@
 
 **[Русская версия](README.ru.md)**
 
-A task backlog that lives as markdown files: an AI agent creates them while working on code, and a human
-triages them in a local web app.
-
-- **`backlog` CLI** — creates tasks, takes them into progress, changes their status.
-- **`backlog` skill** for Claude Code — tells the agent when and how to call the CLI.
-- **Web app** — project list, search, filters, epics, links, progress; doesn't create tasks.
-- **Backlog hygiene** — the agent re-checks tasks whose code changed and closes the ones no longer needed;
-  closed tasks are deleted after 7 days.
+**Keep pull requests clean. Never lose an audit finding.**
+
+A personal backlog for Claude Code that lives next to your code as Markdown files. When the agent notices a problem
+outside the task at hand, it doesn't slip a fix into your pull request — it files a task with the file, the line and
+what will break. Findings from audits and code reviews become tasks too, instead of getting lost in chat history.
+
+- **Clean pull requests.** Out-of-scope fixes go to the backlog, not into the diff you review. The Effect tab in
+  statistics shows how many lines stayed out of your pull requests.
+- **Nothing gets lost.** Every finding from an audit or a review is a task with its source (`file:line`), what it
+  risks and a checklist.
+- **Context kept, tokens saved.** A task stores the context the agent needs to pick it up later. On a re-check the
+  agent gets the task's summary, the current code around its line and the diff since the last check — usually
+  enough to decide without re-reading the codebase.
+- **Stays current by itself.** A Stop hook asks the agent to re-check tasks whose code changed. The agent closes
+  fixed ones with the commit as evidence; line numbers follow the code as it moves. Closed tasks are cleaned up
+  after 7 days.
+- **Local and autonomous.** Plain files in `~/backlog`, no account, no cloud. The agent drives it through the skill,
+  so you don't have to touch the CLI — though you can.
+- **Charts when you want them.** Start the local web app to browse and triage tasks and follow the metrics: debt by
+  week, where it hurts in the code, how accurate the checks are, what the hook costs in tokens.
+
+It consists of the `backlog` CLI, the `backlog` skill and a Stop hook for Claude Code, and an optional web app.
 
 ## Screenshots
 
@@ -89,7 +103,7 @@ If there's no project yet, `backlog new` creates it.
 | `backlog new --title <t> --category <category> [--type task\|epic] [--priority low\|medium\|high\|critical] [--tags a,b] [--found review\|incidental] [--source file:line] [--epic ID] [--blocked-by ID,…] [--related ID,…] [--project id] [--force] [--json]` | Creates a task, the description is read from stdin; a similar open task refuses the command (code 3), `--force` creates it anyway; `--found review` marks a review finding, the default is `incidental` (noticed in passing) |
 | `backlog list [--query q] [--status s,…] [--tag t,…] [--project id \| --all-projects] [--json]` | Lists tasks, by default the open tasks of the current project |
 | `backlog show <ID> [--json]` | The full task: links, blockers, warnings |
-| `backlog take <ID> \| --next [--project id] [--force] [--json]` | Takes a task into progress, checking blockers |
+| `backlog take <ID> [--force] [--json]` \| `--next [--project id] [--json]` | Takes a task into progress, checking blockers |
 | `backlog take --path <file\|directory> [--project id] [--json]` | Takes into progress every open task inside the path |
 | `backlog status <ID> <backlog\|in-progress\|blocked\|done\|cancelled>` | Changes the status |
 | `backlog priority <ID> <low\|medium\|high\|critical>` | Changes the priority |
@@ -108,8 +122,11 @@ If there's no project yet, `backlog new` creates it.
 | `backlog service install \| uninstall \| status` | Autostarts the web server at login: launchd on macOS, systemd --user on Linux, a Startup-folder script on Windows; `status` shows whether it is installed and responding |
 
 Exit codes: `0` success, `1` argument or rule error, `2` not found, `3` refused (the task is closed,
-blocked, or every matching task is blocked), `4` the command failed, `5` `check` found something to
-re-check.
+blocked, or every matching task is blocked), `4` the command failed, `5` `check` found candidates or task problems to
+work through.
+
+With `--json`, `new`, `show`, and `take` print the same task object (with progress, blockers, and links),
+while `list` and `take --path` print an array of such objects.
 
 A project that's no longer maintained is marked inactive: its tasks drop out of the combined "Projects"
 scope's list and statistics, but the project's own page works as usual. Checks (`backlog check`), the Stop
@@ -224,9 +241,18 @@ the Stop hook by hand:
 rm ~/.claude/skills/backlog   # or $CLAUDE_SKILLS_DIR / $CLAUDE_CONFIG_DIR/skills, if set
 ```
 
-and delete the `Stop` hook entry from `~/.claude/settings.json` (or `$CLAUDE_SETTINGS_PATH`) — on
-macOS/Linux it's the command `command -v backlog >/dev/null && backlog hook stop || true`, on Windows a
-PowerShell command starting with `if (Get-Command backlog.cmd ...)`.
+and delete the `Stop` hook entry from `~/.claude/settings.json` (or `$CLAUDE_SETTINGS_PATH`). On macOS/Linux
+it is
+
+```json
+{ "type": "command", "command": "command -v backlog >/dev/null && backlog hook stop || true" }
+```
+
+and on Windows
+
+```json
+{ "type": "command", "shell": "powershell", "command": "if (Get-Command backlog.cmd -ErrorAction SilentlyContinue) { backlog.cmd hook stop }" }
+```
 
 On Windows, the Startup-folder script does not restart a crashed server the way launchd `KeepAlive` or
 systemd `Restart=on-failure` do — after a crash, run `backlog service install` again or start it with

package/README.ru.md

@@ -4,14 +4,27 @@
 
 **[English version](README.md)**
 
-Беклог задач, который живёт markdown-файлами: их создаёт ИИ-агент во время работы над кодом, а человек
-разбирает в локальном веб-приложении.
-
-- **CLI `backlog`** — создаёт задачи, берёт их в работу, меняет статусы.
-- **Скилл `backlog`** для Claude Code — объясняет агенту, когда и как звать CLI.
-- **Веб-приложение** — список проектов, поиск, фильтры, эпики, связи, прогресс; задачи не создаёт.
-- **Порядок в беклоге** — агент перепроверяет задачи, чей код изменился, и закрывает ненужные; закрытые
-  задачи удаляются через 7 дней.
+**Чистые пулреквесты. Находки аудитов не теряются.**
+
+Личный беклог для Claude Code, который живёт рядом с кодом markdown-файлами. Когда агент замечает проблему вне
+текущей задачи, он не протаскивает правку в ваш пулреквест, а заводит задачу: файл, строка и чем это грозит.
+Находки аудитов и ревью тоже становятся задачами, а не теряются в истории чата.
+
+- **Чистые пулреквесты.** Посторонние правки уходят в беклог, а не в дифф, который вы ревьюите. Вкладка «Эффект»
+  в статистике показывает, сколько строк не попало в пулреквесты.
+- **Ничего не теряется.** Каждая находка аудита или ревью — задача с источником (`файл:строка`), описанием риска
+  и чеклистом.
+- **Контекст сохранён, токены сэкономлены.** Задача хранит контекст, который нужен агенту, чтобы потом взять её
+  в работу. При перепроверке агент получает суть задачи, текущий код вокруг её строки и изменения с прошлой
+  проверки — обычно этого хватает, чтобы решить, не перечитывая кодовую базу.
+- **Сам следит за актуальностью.** Stop-хук просит агента перепроверить задачи, чей код изменился. Агент закрывает
+  исправленные со ссылкой на коммит, номера строк следуют за кодом. Закрытые задачи удаляются через 7 дней.
+- **Локальный и автономный.** Обычные файлы в `~/backlog`, без аккаунта и облака. Агент работает с ним через
+  скилл, так что трогать CLI не обязательно — но можно.
+- **Графики — когда нужны.** Поднимите локальное веб-приложение, чтобы просматривать и разбирать задачи и следить
+  за метриками: долг по неделям, где болит в коде, насколько точны проверки, во что обходится хук в токенах.
+
+Состоит из CLI `backlog`, скилла `backlog` и Stop-хука для Claude Code и веб-приложения по желанию.
 
 ## Скриншоты
 
@@ -88,7 +101,7 @@
 | `backlog new --title <t> --category <категория> [--type task\|epic] [--priority low\|medium\|high\|critical] [--tags a,b] [--found review\|incidental] [--source файл:строка] [--epic ID] [--blocked-by ID,…] [--related ID,…] [--project id] [--force] [--json]` | Создаёт задачу, описание читается из stdin; похожая открытая задача — отказ (код 3), `--force` создаёт всё равно; `--found review` — находка ревью, по умолчанию `incidental` (замечено попутно) |
 | `backlog list [--query q] [--status s,…] [--tag t,…] [--project id \| --all-projects] [--json]` | Список задач, по умолчанию открытые задачи текущего проекта |
 | `backlog show <ID> [--json]` | Задача целиком: связи, блокеры, предупреждения |
-| `backlog take <ID> \| --next [--project id] [--force] [--json]` | Берёт задачу в работу, проверяя блокеры |
+| `backlog take <ID> [--force] [--json]` \| `--next [--project id] [--json]` | Берёт задачу в работу, проверяя блокеры |
 | `backlog take --path <файл\|каталог> [--project id] [--json]` | Берёт в работу все открытые задачи внутри пути |
 | `backlog status <ID> <backlog\|in-progress\|blocked\|done\|cancelled>` | Меняет статус |
 | `backlog priority <ID> <low\|medium\|high\|critical>` | Меняет приоритет |
@@ -108,7 +121,10 @@
 
 Коды выхода: `0` — успех, `1` — ошибка аргументов или правил, `2` — не найдено, `3` — отказ (задача
 закрыта, заблокирована или все подходящие заблокированы), `4` — команда не выполнилась, `5` — у `check`
-есть что перепроверить.
+есть кандидаты или проблемы задач, которые надо разобрать.
+
+С `--json` команды `new`, `show` и `take` печатают один и тот же объект задачи (с прогрессом, блокерами и
+связями), а `list` и `take --path` — массив таких объектов.
 
 Проект, который больше не ведётся, помечается неактивным: его задачи не попадают в список и статистику
 режима «Проекты», но страница проекта работает как обычно. Проверки (`backlog check`), Stop-хук и
@@ -219,9 +235,18 @@ npm uninstall -g p-backlog
 rm ~/.claude/skills/backlog   # или $CLAUDE_SKILLS_DIR / $CLAUDE_CONFIG_DIR/skills, если заданы
 ```
 
-и удалите запись хука `Stop` из `~/.claude/settings.json` (или `$CLAUDE_SETTINGS_PATH`) — на
-macOS/Linux это команда `command -v backlog >/dev/null && backlog hook stop || true`, на Windows —
-команда PowerShell, начинающаяся с `if (Get-Command backlog.cmd ...)`.
+и удалите запись хука `Stop` из `~/.claude/settings.json` (или `$CLAUDE_SETTINGS_PATH`). На macOS/Linux
+это
+
+```json
+{ "type": "command", "command": "command -v backlog >/dev/null && backlog hook stop || true" }
+```
+
+а на Windows
+
+```json
+{ "type": "command", "shell": "powershell", "command": "if (Get-Command backlog.cmd -ErrorAction SilentlyContinue) { backlog.cmd hook stop }" }
+```
 
 На Windows скрипт в папке «Автозагрузка» не перезапускает сервер после падения — в отличие от `KeepAlive`
 у launchd или `Restart=on-failure` у systemd; после сбоя запустите `backlog service install` заново или