p-backlog 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.2.0
+
+- Two interface languages: Russian and English (`backlog config language`, RU/EN switch in the web UI).
+- Installable as an npm package: `npm i -g p-backlog`.
+- `backlog setup` installs the agent skill and the Stop hook (replaces `npm run install-skill` from a clone).
+- `backlog serve` runs the web UI; `backlog service install|uninstall|status` starts it at login on macOS (launchd), Linux (systemd --user) and Windows (Startup folder).
+- Claude Code directory respects `CLAUDE_CONFIG_DIR`.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,218 @@
+# p-backlog
+
+**[Русская версия](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.
+
+## Getting started
+
+1. **Install** (needs Node.js 22.13 or newer):
+
+   ```bash
+   npm i -g p-backlog
+   backlog setup --service
+   ```
+
+   `npm i -g p-backlog` installs the CLI globally; `backlog setup --service` installs the skill and the
+   Stop hook for Claude Code and starts the web app as an autostart service.
+
+2. **Language** — defaults to Russian if a backlog already exists, otherwise to the system locale.
+   Change it any time:
+
+   ```bash
+   backlog config language en   # or ru
+   ```
+
+3. **First project and task** — open Claude Code in your repository and ask it to log something to the
+   backlog, or create a task yourself:
+
+   ```bash
+   backlog new --title "Upload timeout ignores file size" --category bug <<<'Problem description'
+   ```
+
+   `backlog new` creates the project for the current repository itself if it doesn't exist yet.
+
+4. **Web app** — already running at `http://localhost:4317`; check with:
+
+   ```bash
+   backlog service status
+   ```
+
+5. **The Stop hook and alerts** — after each of the agent's turns in a repository, the Stop hook checks
+   whether the code behind that project's open tasks changed, and if so asks the agent to re-check them.
+   It also surfaces alerts — signals about the backlog's health (growing debt, stuck tasks, stale
+   low-priority tasks, and so on); `backlog stats` shows the same summary.
+
+## Where tasks live
+
+The backlog directory is `~/backlog`, or the path from the `BACKLOG_DIR` variable. Inside it, one
+directory per project:
+
+```
+~/backlog/spa/project.md   # name, prefix, repos
+~/backlog/spa/SPA-12.md    # task: frontmatter + markdown
+```
+
+The project for the current directory is resolved by the git root and the `repos` field in `project.md`.
+If there's no project yet, `backlog new` creates it.
+
+## CLI commands
+
+| Command | What it does |
+|---|---|
+| `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 --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 |
+| `backlog category <ID> <category\|none>` | Changes the category or clears it |
+| `backlog epic <ID> [<ID> …] --to <epic ID\|none>` | Moves tasks into an epic or takes them out of it |
+| `backlog check [--changed] [--project id \| --all-projects] [--json]` | Fixes dangling links and completed epics, finds tasks that are due for a re-check |
+| `backlog close <ID> --as fixed\|obsolete\|duplicate --reason <evidence> [--duplicate-of ID]` | Closes a task with a reason; `fixed` only with a commit hash from the project's repository |
+| `backlog verify <ID> [<ID> …] [--source file:line]` | Marks tasks as still relevant and remembers the code snippet |
+| `backlog prune [--project id \| --all-projects] [--apply]` | Low-priority tasks older than 30 days; `--apply` cancels them |
+| `backlog stats [--project id \| --all-projects] [--json]` | Statistics summary and alerts |
+| `backlog project list \| status <id> active\|inactive \| delete <id> --confirm <id>` | Project activity and deleting a project with its tasks |
+| `backlog hook stop` | The Stop hook for Claude Code: asks the agent to re-check tasks whose code changed |
+| `backlog config language [ru\|en]` | With no value, prints the current backlog language; with a value, changes it |
+| `backlog setup [--service]` | Install the skill and the Stop hook; with `--service`, also the autostart service |
+| `backlog serve [--port N]` | Runs the web server in the current process, on `PORT` or 4317 by default |
+| `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.
+
+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
+hook, and deleting old closed tasks run across all projects, including inactive ones. Deleting a project
+removes the `~/backlog/<id>` directory with all its tasks and journal — both in the UI and the CLI it
+requires typing the project id to confirm.
+
+## Backlog hygiene
+
+- When the agent finishes a turn in a repository where open tasks reference code that changed, the Stop
+  hook asks it to re-check those tasks. On request ("check the backlog"), it goes through the whole
+  project.
+- The agent closes a task that's no longer needed with `backlog close` and evidence; in the UI such tasks
+  are visible under the "Closed by agent" link, and can be reopened.
+- An epic whose tasks are all closed is closed by the server on its own, at startup and once an hour; such
+  epics are also visible under "Closed by agent".
+- Any closed task is deleted after 7 days along with its file — the server does this at startup and once
+  an hour. The server keeps a completed epic's task around until the epic itself closes (for example, while
+  the backlog still has unprocessed files) — the countdown then shows "deletion delayed" instead.
+  Deleted task numbers are never reused.
+
+## Web app
+
+```bash
+backlog serve             # runs the web server in the current process, on PORT or 4317 by default
+backlog serve --port 5000
+```
+
+The server listens on `127.0.0.1` only and reflects directory changes immediately: a task created by the
+agent shows up in an open tab without a reload.
+
+To have it start automatically on login instead, install it as a service (macOS, Linux, and Windows are
+supported):
+
+```bash
+backlog service install     # macOS: launchd, Linux: systemd --user, Windows: script in the Startup folder
+backlog service status      # is it installed, is the server responding
+backlog service uninstall
+```
+
+Logs:
+
+- macOS — `~/Library/Logs/p-backlog.log`
+- Linux — `journalctl --user -u p-backlog`
+- Windows — `%LOCALAPPDATA%\p-backlog\p-backlog.log`
+
+## Migrating from a clone
+
+If you installed p-backlog by cloning the repository, switch to the package:
+
+```bash
+npm i -g p-backlog       # or, from the clone: npm link
+backlog setup --service
+```
+
+`setup` relinks the skill from the clone to the installed package and doesn't add a second copy of the
+Stop hook; with `--service`, `install` overwrites the autostart service in place, so it also replaces a
+`local.p-backlog` LaunchAgent set up by hand from the old plist template.
+
+## Updating
+
+```bash
+npm update -g p-backlog
+backlog service install
+```
+
+The running service keeps executing the old `cli.js` until reinstalled — the web assets on disk are
+already new, but `backlog service install` is what points the service at the new code.
+
+After upgrading Node itself (for example via Homebrew), run `backlog service install` again too: the
+service stores the path to the Node binary it was installed with.
+
+## Uninstalling
+
+```bash
+backlog service uninstall
+npm uninstall -g p-backlog
+```
+
+Run `backlog service uninstall` before removing the package — otherwise launchd's `KeepAlive` (or systemd's
+`Restart=on-failure`) keeps relaunching a `cli.js` that no longer exists. Then remove the skill link and
+the Stop hook by hand:
+
+```bash
+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 ...)`.
+
+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
+`backlog serve`.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm link                # global backlog command
+npm run install-skill   # ~/.claude/skills/backlog → skill/backlog and the Stop hook in ~/.claude/settings.json
+```
+
+```bash
+npm start           # builds and serves on http://localhost:4317
+npm run dev         # server and Vite with hot reload
+```
+
+```bash
+npm test            # unit, server, and UI tests
+npm run typecheck
+npm run lint
+
+npx playwright install chromium   # once, before the first e2e run
+npm run test:e2e                  # Playwright: live list update
+
+npm run test:package              # the tarball install path end to end on this OS (slow)
+```
+
+To try a build the way a published package would install, without publishing it:
+
+```bash
+npm pack && npm i -g ./p-backlog-0.2.0.tgz
+```

package/README.ru.md

@@ -0,0 +1,213 @@
+# p-backlog
+
+**[English version](README.md)**
+
+Беклог задач, который живёт markdown-файлами: их создаёт ИИ-агент во время работы над кодом, а человек
+разбирает в локальном веб-приложении.
+
+- **CLI `backlog`** — создаёт задачи, берёт их в работу, меняет статусы.
+- **Скилл `backlog`** для Claude Code — объясняет агенту, когда и как звать CLI.
+- **Веб-приложение** — список проектов, поиск, фильтры, эпики, связи, прогресс; задачи не создаёт.
+- **Порядок в беклоге** — агент перепроверяет задачи, чей код изменился, и закрывает ненужные; закрытые
+  задачи удаляются через 7 дней.
+
+## Как начать
+
+1. **Установка** (нужен Node.js 22.13 или новее):
+
+   ```bash
+   npm i -g p-backlog
+   backlog setup --service
+   ```
+
+   `npm i -g p-backlog` ставит CLI глобально; `backlog setup --service` ставит скилл и хук Stop для Claude
+   Code и запускает веб как службу автозапуска.
+
+2. **Язык** — по умолчанию русский, если беклог уже есть, иначе язык берётся из локали системы. Сменить
+   можно в любой момент:
+
+   ```bash
+   backlog config language en   # или ru
+   ```
+
+3. **Первый проект и первая задача** — откройте Claude Code в своём репозитории и попросите «запиши в
+   беклог …», либо создайте задачу сами:
+
+   ```bash
+   backlog new --title "Таймаут загрузки не учитывает размер файла" --category bug <<<'Описание проблемы'
+   ```
+
+   Проект для текущего репозитория `backlog new` создаст сам, если его ещё нет.
+
+4. **Веб-приложение** — уже работает на `http://localhost:4317`; проверить можно так:
+
+   ```bash
+   backlog service status
+   ```
+
+5. **Хук Stop и тревоги** — после каждого ответа агента в репозитории хук Stop проверяет, не изменился ли
+   код у открытых задач этого проекта, и просит агента перепроверить их, если да. Он же показывает
+   тревоги — сигналы о состоянии беклога (растущий долг, зависшие задачи, старые задачи с низким
+   приоритетом и т. п.); их сводку показывает и `backlog stats`.
+
+## Где лежат задачи
+
+Каталог беклога — `~/backlog` или путь из переменной `BACKLOG_DIR`. Внутри — по каталогу на проект:
+
+```
+~/backlog/spa/project.md   # name, prefix, repos
+~/backlog/spa/SPA-12.md    # задача: frontmatter + markdown
+```
+
+Проект для текущей директории определяется по git-корню и полю `repos` в `project.md`. Если проекта нет,
+`backlog new` создаёт его сам.
+
+## Команды CLI
+
+| Команда | Что делает |
+|---|---|
+| `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 --path <файл\|каталог> [--project id] [--json]` | Берёт в работу все открытые задачи внутри пути |
+| `backlog status <ID> <backlog\|in-progress\|blocked\|done\|cancelled>` | Меняет статус |
+| `backlog priority <ID> <low\|medium\|high\|critical>` | Меняет приоритет |
+| `backlog category <ID> <категория\|none>` | Меняет категорию или убирает её |
+| `backlog epic <ID> [<ID> …] --to <ID эпика\|none>` | Переносит задачи в эпик или вынимает из него |
+| `backlog check [--changed] [--project id \| --all-projects] [--json]` | Чинит висячие ссылки и завершённые эпики, находит задачи, которые пора перепроверить |
+| `backlog close <ID> --as fixed\|obsolete\|duplicate --reason <улика> [--duplicate-of ID]` | Закрывает задачу с причиной; `fixed` — только с хешем коммита из репозитория проекта |
+| `backlog verify <ID> [<ID> …] [--source файл:строка]` | Отмечает, что задачи ещё актуальны, и запоминает фрагмент кода |
+| `backlog prune [--project id \| --all-projects] [--apply]` | Задачи с низким приоритетом старше 30 дней; `--apply` отменяет их |
+| `backlog stats [--project id \| --all-projects] [--json]` | Сводка статистики и тревоги |
+| `backlog project list \| status <id> active\|inactive \| delete <id> --confirm <id>` | Активность проектов и удаление проекта вместе с задачами |
+| `backlog hook stop` | Хук Stop для Claude Code: просит агента перепроверить задачи, чей код изменился |
+| `backlog config language [ru\|en]` | Без значения — печатает текущий язык беклога; со значением — меняет его |
+| `backlog setup [--service]` | Поставить скилл и Stop-хук; с `--service` — ещё и службу автозапуска |
+| `backlog serve [--port N]` | Запускает веб-сервер в текущем процессе, порт — из `PORT`, иначе 4317 |
+| `backlog service install \| uninstall \| status` | Автозапуск веб-сервера при входе: launchd на macOS, systemd --user на Linux, скрипт в папке «Автозагрузка» на Windows; `status` — установлена ли служба и отвечает ли сервер |
+
+Коды выхода: `0` — успех, `1` — ошибка аргументов или правил, `2` — не найдено, `3` — отказ (задача
+закрыта, заблокирована или все подходящие заблокированы), `4` — команда не выполнилась, `5` — у `check`
+есть что перепроверить.
+
+Проект, который больше не ведётся, помечается неактивным: его задачи не попадают в список и статистику
+режима «Проекты», но страница проекта работает как обычно. Проверки (`backlog check`), Stop-хук и
+удаление старых закрытых задач идут по всем проектам, включая неактивные. Удаление проекта сносит каталог
+`~/backlog/<id>` со всеми задачами и журналом — и в интерфейсе, и в CLI оно требует ввести id проекта.
+
+## Порядок в беклоге
+
+- Агент заканчивает ответ в репозитории, где открытые задачи ссылаются на изменившийся код, — хук Stop
+  просит его перепроверить эти задачи. По просьбе «проверь беклог» он проходит весь проект.
+- Ненужную задачу агент закрывает через `backlog close` с уликой; в интерфейсе такие задачи видны по
+  ссылке «Закрыты агентом», их можно вернуть в беклог.
+- Эпик, все задачи которого закрыты, сервер при старте и раз в час закрывает сам; такие эпики тоже видны
+  по ссылке «Закрыты агентом».
+- Любая закрытая задача удаляется через 7 дней вместе с файлом: это делает сервер при старте и раз в час. Задачу завершённого эпика сервер держит, пока эпик не закроется (например, пока в беклоге есть неразобранные файлы), — тогда вместо отсчёта видно «удаление задержано».
+  Номера удалённых задач повторно не выдаются.
+
+## Веб-приложение
+
+```bash
+backlog serve             # запускает веб-сервер в текущем процессе, порт — из PORT, иначе 4317
+backlog serve --port 5000
+```
+
+Сервер слушает только `127.0.0.1` и показывает изменения каталога сразу: задача, созданная агентом,
+появляется в открытой вкладке без перезагрузки.
+
+Чтобы сервер поднимался сам при входе в систему, установите его как службу (поддерживаются macOS, Linux
+и Windows):
+
+```bash
+backlog service install     # macOS: launchd, Linux: systemd --user, Windows: скрипт в папке «Автозагрузка»
+backlog service status      # установлена ли служба, отвечает ли сервер
+backlog service uninstall
+```
+
+Логи:
+
+- macOS — `~/Library/Logs/p-backlog.log`
+- Linux — `journalctl --user -u p-backlog`
+- Windows — `%LOCALAPPDATA%\p-backlog\p-backlog.log`
+
+## Переход с установки из клона
+
+Если p-backlog был установлен из клона репозитория, переходите на пакет:
+
+```bash
+npm i -g p-backlog       # или, из клона: npm link
+backlog setup --service
+```
+
+`setup` переставит ссылку скилла с клона на установленный пакет и не задублирует хук Stop; с
+`--service` `install` перезаписывает службу автозапуска на месте, поэтому заодно заменяет и
+LaunchAgent `local.p-backlog`, настроенный вручную по старому шаблону plist.
+
+## Обновление
+
+```bash
+npm update -g p-backlog
+backlog service install
+```
+
+Запущенная служба продолжает работать со старым `cli.js`, пока её не переустановят, — веб-ресурсы на
+диске уже новые, но именно `backlog service install` переключает службу на новый код.
+
+После обновления самого Node (например, через Homebrew) тоже запустите `backlog service install` —
+служба хранит путь к бинарнику Node, с которым была установлена.
+
+## Удаление
+
+```bash
+backlog service uninstall
+npm uninstall -g p-backlog
+```
+
+Перед удалением пакета выполните `backlog service uninstall` — иначе `KeepAlive` у launchd (или
+`Restart=on-failure` у systemd) продолжит перезапускать несуществующий `cli.js`. Затем вручную уберите
+ссылку на скилл и хук Stop:
+
+```bash
+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 ...)`.
+
+На Windows скрипт в папке «Автозагрузка» не перезапускает сервер после падения — в отличие от `KeepAlive`
+у launchd или `Restart=on-failure` у systemd; после сбоя запустите `backlog service install` заново или
+`backlog serve`.
+
+## Разработка
+
+```bash
+npm install
+npm run build
+npm link            # глобальная команда backlog
+npm run install-skill   # ~/.claude/skills/backlog → skill/backlog и хук Stop в ~/.claude/settings.json
+```
+
+```bash
+npm start           # сборка и сервер на http://localhost:4317
+npm run dev         # сервер и Vite с горячей перезагрузкой
+```
+
+```bash
+npm test            # модульные, серверные и интерфейсные тесты
+npm run typecheck
+npm run lint
+
+npx playwright install chromium   # один раз, перед первым запуском e2e
+npm run test:e2e                  # Playwright: живое обновление списка
+
+npm run test:package              # весь путь установки из tarball на этой ОС (медленный)
+```
+
+Чтобы попробовать сборку так, будто это опубликованный пакет, без публикации:
+
+```bash
+npm pack && npm i -g ./p-backlog-0.2.0.tgz
+```