@dzhechkov/p-replicator 1.5.6 → 1.5.7

package/README/ru/06_troubleshooting.md

@@ -0,0 +1,355 @@
+# 06. Troubleshooting
+
+Типичные проблемы и пути их решения.
+
+## Установка / `init`
+
+### `init` отказывается работать: «P-Replicator is already installed»
+
+```bash
+# Если хотите upgrade с preserve customizations:
+npx @dzhechkov/p-replicator update
+
+# Или через init --force (тоже preserves customizations):
+npx @dzhechkov/p-replicator init --force
+
+# Полный сброс к defaults (потеряете user hooks):
+npx @dzhechkov/p-replicator init --force --reset-settings
+```
+
+### После `init` отсутствуют какие-то файлы
+
+```bash
+npx @dzhechkov/p-replicator doctor
+```
+
+Если что-то fail'ит (e.g., «security.md missing»):
+
+```bash
+npx @dzhechkov/p-replicator init --force      # полная переустановка pre-shipped
+```
+
+### Установка пошла в `~/node_modules`, а не в проект
+
+Cause: в проекте нет `package.json`, npm walk'ает вверх и находит `package.json`
+в home-директории.
+
+Fix: создайте `package.json` в корне проекта:
+
+```bash
+npm init -y
+npx @dzhechkov/p-replicator init
+```
+
+---
+
+## После `/replicate`
+
+### `/replicate` не сгенерировала ожидаемые команды (`/run`, `/feature`, `/myinsights`, ...)
+
+**Это решено в v1.4.0+.** Теперь все 11 generic команд **pre-shipped** через
+`init` — `/replicate` Phase 3 их не генерирует, только enhance'ит project-specific
+артефакты.
+
+Если у вас старая версия (≤1.3.x):
+
+```bash
+npx @dzhechkov/p-replicator@latest init --force
+```
+
+После обновления `verify` покажет полный набор:
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+
+### `/replicate` Phase 3 пишет «Generate /commands/start.md»
+
+Это устаревшая formulation в `replicate.md`. Должна быть `Pre-shipped... do
+NOT overwrite`. Если видите эту фразу:
+
+```bash
+npx @dzhechkov/p-replicator@latest update    # обновит replicate.md
+```
+
+В v1.4.0+ есть meta-test который ловит эту регрессию. См.
+`tests/e2e/lifecycle.test.js` describe `meta: doc-consistency`.
+
+### Project-specific агенты (planner.md, architect.md) не созданы
+
+Это нормально если `/replicate` Phase 3 ещё не запускалась. Запустите
+`/replicate "описание"` в Claude Code.
+
+`verify` показывает их как **hints** (warning, не error) если `CLAUDE.md` или
+`feature-roadmap.json` есть, но agents отсутствуют.
+
+---
+
+## Hooks / Statusline
+
+### Statusline не отображается
+
+**Проверки:**
+
+1. Версия Claude Code поддерживает `statusLine` config? Обновите Claude Code до
+   последней.
+2. Поле `statusLine` присутствует в `.claude/settings.json`?
+   ```bash
+   cat .claude/settings.json | grep -A 3 statusLine
+   ```
+3. Скрипт работает напрямую?
+   ```bash
+   node .claude/hooks/statusline.cjs
+   ```
+   Должен вывести 6 строк ANSI-output.
+
+Если 3-й пункт fail'ит:
+
+```bash
+node .claude/hooks/statusline.cjs 2>&1
+```
+
+Покажет stack trace. Скорее всего corrupt JSON или отсутствует `.p-replicator.json`.
+
+### Hooks не auto-commit'ят
+
+```bash
+npx @dzhechkov/p-replicator doctor
+```
+
+В секции `Prerequisites:` должно быть:
+
+```
+✓ git on PATH
+```
+
+Если `✗ git NOT on PATH` — установите git, добавьте в PATH.
+
+Также проверьте что `.git` директория существует (вы в репозитории):
+
+```bash
+git rev-parse --git-dir
+```
+
+### Хуки запускаются но ничего не коммитят
+
+**Cause:** `.git` есть, но нет changes для коммита (что нормально).
+
+**Debug:** напрямую:
+
+```bash
+node .claude/hooks/autocommit-roadmap.cjs
+echo "Exit: $?"
+git log -1 --format="%s"
+```
+
+Если файл не в манифесте git, сделайте `git add .claude/feature-roadmap.json`
+вручную один раз.
+
+### Statusline показывает «Settings ⚠️ merged» хотя я ничего не менял
+
+Cause: какой-то процесс модифицировал `settings.json` (формат, whitespace,
+ordering). Statusline сравнивает через deep-equals по sorted keys.
+
+Fix:
+
+```bash
+npx @dzhechkov/p-replicator init --force --reset-settings
+```
+
+### Settings.json потерял мои custom hooks после update
+
+**Это БЫЛ bug до v1.4.2.** В v1.4.2+ `update` и `init --force` используют
+`mergeSettingsJson` который preserves user customizations.
+
+Если вы на v1.4.1 или раньше:
+
+```bash
+npx @dzhechkov/p-replicator@latest update
+```
+
+Если потеряли hooks безвозвратно — восстановите вручную из git history:
+
+```bash
+git log -p --follow -- .claude/settings.json
+```
+
+---
+
+## Roadmap / `--feature-branches`
+
+### `/run --feature-branches` сразу fail'ит «not on main»
+
+Cause: вы на feature-branch'е (не на main).
+
+```bash
+git status
+git checkout main           # переключиться
+/run mvp --feature-branches
+```
+
+### `--feature-branches` потерял мои несохранённые changes
+
+Они в stash:
+
+```bash
+git stash list                              # список stash'ей
+git stash show stash@{0}                    # preview
+git stash pop                               # восстановить (или git stash drop для удаления)
+```
+
+`p-replicator` auto-stash'ит с message «auto-stash before /run feature-branches».
+
+### Feature branch без `number` в roadmap
+
+Cause: roadmap создан до v1.5.0 (нет `number` field).
+
+`--feature-branches` flag auto-assign'ит `number = max(numbers) + 1` при
+первом encounter, persists обратно. Просто прогоните `/run mvp --feature-branches`
+ещё раз — numbers заполнятся.
+
+---
+
+## Tests / Snapshot
+
+### `npm test` fail'ит после моих изменений в template
+
+```bash
+npm test 2>&1 | head -30                    # увидеть какие тесты упали
+```
+
+Типичные причины:
+
+1. **Snapshot test fail** — изменились templates, baseline устарел.
+   ```bash
+   npm run snapshot:baseline                # перегенерировать
+   npm test                                 # должно стать зелёным
+   ```
+
+2. **Meta-test fail** — `replicate-pipeline.md` или `replicate.md` упоминают
+   pre-shipped command в неправильной секции. Проверьте сами edits.
+
+3. **Unit test fail на COMPONENTS** — нарушили SSOT. Проверьте что добавили
+   `kind`, `items`, `label` в новый component group.
+
+### `verify` показывает orphan'ы post-init
+
+Cause: вы upgrade'нулись с старой версии (≤1.4.2) которая не tracked
+`shippedDefaults`. Orphan detection skipped на первый upgrade.
+
+Fix:
+
+```bash
+npx @dzhechkov/p-replicator init --force    # populate shippedDefaults в manifest
+npx @dzhechkov/p-replicator init --force    # второй прогон удалит реальные orphan'ы (если они есть)
+```
+
+После этого orphan detection будет работать на каждом subsequent upgrade.
+
+---
+
+## Insights
+
+### Insights не auto-injected в новую сессию
+
+**Проверки:**
+
+1. `.claude/insights/index.md` существует и содержит entries?
+   ```bash
+   wc -l .claude/insights/index.md
+   grep -c "^## " .claude/insights/index.md      # количество entries
+   ```
+2. Hook `session-insights.cjs` работает?
+   ```bash
+   node .claude/hooks/session-insights.cjs
+   ```
+   Должен вывести `## Recent project insights\n\n## ... ## ... ## ...`.
+3. SessionStart hook configured?
+   ```bash
+   cat .claude/settings.json | grep -A 5 SessionStart
+   ```
+
+Если все 3 OK, но всё равно не работает — Claude Code может cache'ировать
+session context. Перезапустите `claude`.
+
+### `/myinsights recall <query>` ничего не находит
+
+Cause: query не матчит tags. Recall — case-insensitive substring search по
+tags + body.
+
+Tip: проверьте tags entries:
+
+```bash
+grep "^\*\*Tags:" .claude/insights/index.md | head -10
+```
+
+Подберите более специфичный query (e.g., `prisma` вместо `bug`).
+
+---
+
+## MCP servers
+
+### MCP servers не connect'ятся
+
+Это вне scope `p-replicator` — это Claude Code config. Проверьте:
+
+```bash
+cat .mcp.json                           # формат правильный?
+claude --debug                          # MCP errors в logs?
+```
+
+Statusline показывает количество server'ов из `.mcp.json` независимо от их
+working state.
+
+---
+
+## Performance
+
+### Statusline тормозит при каждой команде
+
+**Cause:** очень большие docs/ или filesystem-trees.
+
+**Diagnose:**
+
+```bash
+time node .claude/hooks/statusline.cjs    # сколько секунд?
+```
+
+Должно быть < 100ms. Если > 1s — проверьте размер `docs/`:
+
+```bash
+du -sh docs/
+find docs/ -type f -name "*.md" | wc -l
+```
+
+**Workaround:** временно отключить statusline через удаление `statusLine`
+поля в `.claude/settings.json`.
+
+См. `KNOWN_LIMITATIONS.md` пункт L6 — будущий enhancement: env-var
+`STATUSLINE_PROFILE=1` для измерения каждой секции.
+
+---
+
+## Версионные несовместимости
+
+### Я на старой версии. Стоит ли upgrading?
+
+| Текущая → Целевая | Что получите | Migration cost |
+|---|---|---|
+| 1.3.x → 1.5.0 | Все pre-shipped команды + statusline + feature-branches + merge-логика | Запустите `init --force` (preserves customizations) |
+| 1.4.0 → 1.4.1 | Cross-platform hooks + sync merge mode | `init --force` |
+| 1.4.1 → 1.4.2 | Settings merge (preserve customizations) | `init --force` сразу безопасен (preserves) |
+| 1.4.2 → 1.4.3 | Orphan detection | Первый upgrade без baseline — re-run `init --force` для populate |
+| 1.4.3 → 1.5.0 | Statusline + --feature-branches | `update` или `init --force` |
+
+Полная история — в [07_changelog.md](./07_changelog.md) или
+`CHANGELOG.md` (авторитетный).
+
+---
+
+## Если ничего не помогает
+
+1. Прочитайте `KNOWN_LIMITATIONS.md` — может это известное ограничение
+2. Запустите `verify` + `doctor` — соберите exact output
+3. Issue: https://github.com/dzhechko/pu-unicorn-replicate/issues
+   приложите версию, output `verify`, шаги воспроизведения

package/README/ru/07_changelog.md

@@ -0,0 +1,146 @@
+# 07. Changelog (краткая версия)
+
+Эволюция пакета по релизам. Полные detail'и — в `../../CHANGELOG.md`
+(авторитетный источник).
+
+## v1.5.0 — 2026-05-07
+
+**Две фичи + 12 новых тестов.**
+
+- ✨ **Statusline dashboard** (RuFlo-style 6-line multi-line status bar) через
+  `templates/.claude/hooks/statusline.cjs`
+- ✨ **`--feature-branches` flag** для `/run` и `/go` (workflow для обучения /
+  демо: каждая фича на отдельной ветке `feature/{NNN}-{id}`)
+- 🆕 `state-update.cjs` — argv-driven helper для pipeline команд писать прогресс
+- 🆕 Roadmap schema расширена: `number` (auto-assigned), `branch` (populated при
+  done)
+- 🆕 `--auto-merge` companion flag (off by default)
+- 📊 105 tests / 36 suites / 113 → 115 файлов в snapshot baseline
+
+## v1.4.3 — 2026-05-07
+
+**Orphan hook detection.**
+
+- 🐛 **Closed last v1.4.2 limitation:** `mergeSettingsJson` теперь cleans
+  hooks которые были shipped в прошлой версии но удалены в новой
+- 🆕 `manifest.shippedDefaults['settings.json']` — baseline для orphan detection
+- 🆕 `removeOrphanHooks(existing, oldTpl, newTpl)` helper
+- 🐛 **Bonus fix:** `update.js` теперь тоже использует merge-логику (был bug:
+  blindly overwrite settings.json)
+- 📊 93 tests, +8 от v1.4.2
+
+## v1.4.2 — 2026-05-06
+
+**3 v1.4.1 limitations устранены.**
+
+- 🐛 `init --force` теперь MERGE settings.json (preserves user customizations)
+- 🆕 `--reset-settings` flag для explicit nuclear-overwrite
+- 🐛 Stronger meta-test для `replicate.md` drift (multi-axis: verbs +
+  section-scope + list-style + allowlist)
+- 🆕 `doctor` checks `git on PATH` (Prerequisites section) — explains why
+  autocommit hooks could silently no-op
+- 📊 85 tests, +11 от v1.4.1
+
+## v1.4.1 — 2026-05-06
+
+**3 v1.4.0 limitations + 1 critical regression discovery.**
+
+- 🐛 **Cross-platform hooks:** заменены bash-chains на 4 Node-скрипта
+  (`session-insights`, `autocommit-{roadmap,insights,plans}`)
+- 🐛 **`verify.js` SSOT:** `kind: 'pre-shipped' | 'project-generated'` field
+  + 3 новых project-generated groups
+- 🐛 **Meta-tests** для `replicate.md` ↔ `replicate-pipeline.md` consistency
+- 🐛 **Critical regression discovered + fixed:** `sync-templates.js` cleanDir
+  тихо удалял pre-shipped файлы во время `npm publish --dry-run`. Switched to
+  MERGE mode
+- 🆕 6th COMPONENTS group: `hooks` (4 cross-platform Node scripts)
+- 🆕 `getItemRelativePath()` helper для централизованного path-derivation
+- 📊 74 tests, +14 от v1.4.0
+
+## v1.4.0 — 2026-05-06
+
+**Major release — 9 pre-shipped команд + verify command.**
+
+- ✨ Закрыт корневой источник pain: `/replicate` Phase 3 больше не пытается
+  генерировать generic команды. Все 11 commands + 5 rules + settings.json +
+  4 hooks теперь pre-shipped через `init`
+- ✨ **9 новых pre-shipped команд:** `/start`, `/plan`, `/feature`, `/go`,
+  `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
+- ✨ **3 новых pre-shipped rules:** `git-workflow`, `insights-capture`,
+  `feature-lifecycle`
+- ✨ **Settings.json shipped** with hooks (SessionStart insights inject + Stop
+  auto-commit)
+- ✨ **`verify` command** — replaces user's manual verification prompt
+- 🐛 5 sources of truth divergence (`replicate.md`, `replicate-pipeline.md`,
+  cc-toolkit modules, README, cli help) unified via `utils.COMPONENTS.items`
+- 📊 60 tests, +8 от v1.3.1
+
+## v1.3.1 — 2026-05-06
+
+**Two real bug fixes.**
+
+- 🐛 **`cli.js` --help showed «1 rule» while `EXPECTED_RULES` had 2 entries.**
+  SSOT fix: `COMPONENTS.<group>.items` map is single source of truth for
+  counts, used by doctor/list/cli.js help via dynamic derivation
+- 🐛 **`update.js` corrupted manifest** — walked user's full `.claude/`,
+  capturing project-generated files into `manifest.files`. Subsequent
+  `remove` would delete them, contradicting documented behavior. Fixed by
+  using `getRelativePaths(templateClaude)` instead
+- 🐛 Bonus: `update` now removes orphan template files (files in old manifest
+  but not in new template) — addresses original v1.3.0 concern about ignored
+  `missing[]` from `diffFiles`
+- 📊 52 tests, +7 от v1.3.0
+
+## v1.3.0 (baseline)
+
+Initial published version. 10 skills, 2 commands (`/replicate`, `/harvest`),
+4 agents, 2 rules. SPARC documentation pipeline + knowledge extraction.
+
+---
+
+## Migration по версиям
+
+| From → To | Команда |
+|---|---|
+| 1.3.x → 1.5.0 | `npx @dzhechkov/p-replicator@1.5.0 init --force` (preserves customizations) |
+| Любая → latest | `npx @dzhechkov/p-replicator@latest update` |
+| Полный reset | `... init --force --reset-settings` (потеряете custom hooks) |
+
+После любого upgrade — `verify` для проверки contract:
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+
+---
+
+## Patterns persisted в AQE memory
+
+Каждое значимое улучшение зафиксировано как pattern (для cross-session
+learning):
+
+- v1.3.1: `cli-package-ssot-component-lists`, `cli-package-manifest-preservation`,
+  `tdd-red-test-must-trigger-bug`
+- v1.4.0: `cli-package-pre-ship-vs-generate-boundary`,
+  `cli-package-verify-replaces-manual-prompts`,
+  `documentation-source-of-truth-divergence`
+- v1.4.1: `cli-package-cross-platform-hooks-via-node-scripts`,
+  `cli-package-kind-discrimination-for-ssot`,
+  `npm-package-prepublish-clean-and-replace-anti-pattern`
+- v1.4.2: `cli-package-settings-json-merge-vs-overwrite`,
+  `meta-test-multi-axis-drift-detection`, `cli-doctor-prerequisites-section`
+- v1.4.3: `cli-shipped-defaults-baseline-for-orphan-detection`,
+  `cli-update-must-mirror-init-merge-logic`
+- v1.5.0: `cli-statusline-multi-line-dashboard`,
+  `cli-feature-branches-flag-for-teaching-workflows`
+
+Каждый pattern содержит: context, problem, solution, verification, tradeoffs,
+applied-to (version/file).
+
+---
+
+## Полный CHANGELOG
+
+См. `../../CHANGELOG.md` — авторитетный источник с полным detail'ями всех
+версий, migration notes, breaking changes (которых не было — все upgrade'ы
+backward-compatible).

package/README/ru/README.md

@@ -0,0 +1,60 @@
+# Документация @dzhechkov/p-replicator
+
+Полный комплект документации к npm-пакету `@dzhechkov/p-replicator` —
+toolkit для AI-assisted разработки в Claude Code (Vibe Coding).
+
+## Что это
+
+`p-replicator` устанавливает в проект готовый набор `.claude/`-инструментов:
+**11 slash-команд**, **10 skills**, **4 агента**, **5 правил**, **6 hook-скриптов**
+и `settings.json` с pre-configured хуками. Главная команда `/replicate`
+проводит проект через 5-фазный pipeline (Discovery → Planning → Validation →
+Toolkit Generation → Finalize), генерирует SPARC-документацию и project-specific
+артефакты.
+
+## Навигация
+
+| Раздел | Описание |
+|---|---|
+| [01_quickstart.md](./01_quickstart.md) | Установка, первый запуск, проверка |
+| [02_user_guide.md](./02_user_guide.md) | Все команды и workflow с примерами |
+| [03_admin_guide.md](./03_admin_guide.md) | Настройка hooks, settings.json, statusline, insights |
+| [04_api_reference.md](./04_api_reference.md) | CLI-флаги, схемы манифеста, roadmap, state |
+| [05_architecture.md](./05_architecture.md) | Архитектура: pre-shipped vs generated, SSOT, hooks |
+| [06_troubleshooting.md](./06_troubleshooting.md) | Решение типичных проблем |
+| [07_changelog.md](./07_changelog.md) | История версий 1.3.x → 1.5.x |
+
+## Языки
+
+- 🇷🇺 [Документация на русском](./README.md) (вы здесь)
+- 🇬🇧 [English documentation](../eng/README.md)
+
+## Версия
+
+`@dzhechkov/p-replicator@1.5.0` (последняя стабильная). См. история всех
+изменений в `../../CHANGELOG.md` (авторитетный источник).
+
+## Быстрый старт
+
+```bash
+cd ваш-проект
+npx @dzhechkov/p-replicator init
+claude                              # открыть Claude Code
+/replicate "описание вашего продукта"
+```
+
+После завершения `/replicate` запустите `/run mvp` для автономной сборки фич
+из roadmap'а или `/start` для bootstrap'а scaffold'а.
+
+## Связанные репозитории
+
+- npm: https://www.npmjs.com/package/@dzhechkov/p-replicator
+- GitHub: https://github.com/dzhechko/pu-unicorn-replicate
+- Issues: https://github.com/dzhechko/pu-unicorn-replicate/issues
+
+## Companion-документация (внутри пакета)
+
+- `../../CHANGELOG.md` — история версий
+- `../../KNOWN_LIMITATIONS.md` — открытые задачи на улучшение (7 пунктов)
+- `../../MULTIPLATFORM_ROADMAP.md` — roadmap поддержки Codex/OpenCode/KiloCode
+- `../../README.md` — короткое user-facing intro