@dzhechkov/p-replicator 1.5.5 → 1.5.7

package/README/eng/06_troubleshooting.md

@@ -0,0 +1,353 @@
+# 06. Troubleshooting
+
+Common issues and resolutions.
+
+## Installation / `init`
+
+### `init` refuses: "P-Replicator is already installed"
+
+```bash
+# To upgrade preserving customizations:
+npx @dzhechkov/p-replicator update
+
+# Or via init --force (also preserves customizations):
+npx @dzhechkov/p-replicator init --force
+
+# Full reset to defaults (loses user hooks):
+npx @dzhechkov/p-replicator init --force --reset-settings
+```
+
+### Missing files after `init`
+
+```bash
+npx @dzhechkov/p-replicator doctor
+```
+
+If anything fails (e.g., "security.md missing"):
+
+```bash
+npx @dzhechkov/p-replicator init --force      # full pre-shipped reinstall
+```
+
+### Install went to `~/node_modules` instead of project
+
+Cause: no `package.json` in your project, npm walks up and finds one in
+home directory.
+
+Fix: create `package.json` in project root:
+
+```bash
+npm init -y
+npx @dzhechkov/p-replicator init
+```
+
+---
+
+## After `/replicate`
+
+### `/replicate` didn't generate expected commands (`/run`, `/feature`, `/myinsights`, ...)
+
+**This is solved in v1.4.0+.** All 11 generic commands are now **pre-shipped**
+via `init` — `/replicate` Phase 3 doesn't generate them, only enhances
+project-specific artifacts.
+
+If you're on an old version (≤1.3.x):
+
+```bash
+npx @dzhechkov/p-replicator@latest init --force
+```
+
+After upgrade, `verify` will show the full set:
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+
+### `/replicate` Phase 3 says "Generate /commands/start.md"
+
+Stale phrasing in `replicate.md`. Should read "Pre-shipped... do NOT
+overwrite". If you see this:
+
+```bash
+npx @dzhechkov/p-replicator@latest update    # updates replicate.md
+```
+
+In v1.4.0+ a meta-test catches this regression. See
+`tests/e2e/lifecycle.test.js` describe `meta: doc-consistency`.
+
+### Project-specific agents (planner.md, architect.md) not created
+
+Normal if `/replicate` Phase 3 hasn't run yet. Run `/replicate "description"`
+in Claude Code.
+
+`verify` shows them as **hints** (warning, not error) when `CLAUDE.md` or
+`feature-roadmap.json` exists but agents are absent.
+
+---
+
+## Hooks / Statusline
+
+### Statusline doesn't appear
+
+**Checks:**
+
+1. Does your Claude Code version support `statusLine` config? Update Claude Code.
+2. Is `statusLine` field present in `.claude/settings.json`?
+   ```bash
+   cat .claude/settings.json | grep -A 3 statusLine
+   ```
+3. Does the script run directly?
+   ```bash
+   node .claude/hooks/statusline.cjs
+   ```
+   Should print 6 lines of ANSI output.
+
+If point 3 fails:
+
+```bash
+node .claude/hooks/statusline.cjs 2>&1
+```
+
+Shows stack trace. Likely corrupt JSON or missing `.p-replicator.json`.
+
+### Hooks aren't auto-committing
+
+```bash
+npx @dzhechkov/p-replicator doctor
+```
+
+In `Prerequisites:` section, expect:
+
+```
+✓ git on PATH
+```
+
+If `✗ git NOT on PATH` — install git, add to PATH.
+
+Also verify `.git` directory exists (you're in a repo):
+
+```bash
+git rev-parse --git-dir
+```
+
+### Hooks run but don't commit anything
+
+**Cause:** `.git` exists but no changes to commit (which is normal).
+
+**Debug** directly:
+
+```bash
+node .claude/hooks/autocommit-roadmap.cjs
+echo "Exit: $?"
+git log -1 --format="%s"
+```
+
+If a file isn't tracked by git, do `git add .claude/feature-roadmap.json`
+manually once.
+
+### Statusline shows "Settings ⚠️ merged" but I didn't change anything
+
+Cause: some process modified `settings.json` (formatting, whitespace,
+ordering). Statusline compares via deep-equals on sorted keys.
+
+Fix:
+
+```bash
+npx @dzhechkov/p-replicator init --force --reset-settings
+```
+
+### Settings.json lost my custom hooks after update
+
+**This WAS a bug pre-v1.4.2.** In v1.4.2+, `update` and `init --force` use
+`mergeSettingsJson` which preserves user customizations.
+
+If you're on v1.4.1 or earlier:
+
+```bash
+npx @dzhechkov/p-replicator@latest update
+```
+
+If you've irrecoverably lost hooks — restore from git history:
+
+```bash
+git log -p --follow -- .claude/settings.json
+```
+
+---
+
+## Roadmap / `--feature-branches`
+
+### `/run --feature-branches` immediately fails "not on main"
+
+Cause: you're on a feature branch (not main).
+
+```bash
+git status
+git checkout main           # switch to main
+/run mvp --feature-branches
+```
+
+### `--feature-branches` lost my unsaved changes
+
+They're in stash:
+
+```bash
+git stash list                              # list stashes
+git stash show stash@{0}                    # preview
+git stash pop                               # restore (or git stash drop to discard)
+```
+
+`p-replicator` auto-stashes with message "auto-stash before /run feature-branches".
+
+### Feature branch without `number` in roadmap
+
+Cause: roadmap created pre-v1.5.0 (no `number` field).
+
+`--feature-branches` flag auto-assigns `number = max(numbers) + 1` on first
+encounter, persists back. Just run `/run mvp --feature-branches` again —
+numbers fill in.
+
+---
+
+## Tests / Snapshot
+
+### `npm test` fails after my template changes
+
+```bash
+npm test 2>&1 | head -30                    # see which tests fail
+```
+
+Common causes:
+
+1. **Snapshot test fails** — templates changed, baseline outdated.
+   ```bash
+   npm run snapshot:baseline                # regenerate
+   npm test                                 # should be green
+   ```
+
+2. **Meta-test fails** — `replicate-pipeline.md` or `replicate.md` mention
+   pre-shipped command in wrong section. Review your edits.
+
+3. **Unit test fails on COMPONENTS** — broke SSOT. Check that you added
+   `kind`, `items`, `label` to the new component group.
+
+### `verify` shows orphans post-init
+
+Cause: you upgraded from an old version (≤1.4.2) that didn't track
+`shippedDefaults`. Orphan detection skipped on first upgrade.
+
+Fix:
+
+```bash
+npx @dzhechkov/p-replicator init --force    # populate shippedDefaults in manifest
+npx @dzhechkov/p-replicator init --force    # second pass removes real orphans (if any)
+```
+
+After this, orphan detection works on every subsequent upgrade.
+
+---
+
+## Insights
+
+### Insights aren't auto-injected into new sessions
+
+**Checks:**
+
+1. Does `.claude/insights/index.md` exist with entries?
+   ```bash
+   wc -l .claude/insights/index.md
+   grep -c "^## " .claude/insights/index.md      # entry count
+   ```
+2. Does the `session-insights.cjs` hook work?
+   ```bash
+   node .claude/hooks/session-insights.cjs
+   ```
+   Should print `## Recent project insights\n\n## ... ## ... ## ...`.
+3. Is the SessionStart hook configured?
+   ```bash
+   cat .claude/settings.json | grep -A 5 SessionStart
+   ```
+
+If all 3 are OK but still nothing — Claude Code may cache session context.
+Restart `claude`.
+
+### `/myinsights recall <query>` finds nothing
+
+Cause: query doesn't match tags. Recall is case-insensitive substring
+search across tags + body.
+
+Tip: check entry tags:
+
+```bash
+grep "^\*\*Tags:" .claude/insights/index.md | head -10
+```
+
+Use a more specific query (e.g., `prisma` instead of `bug`).
+
+---
+
+## MCP servers
+
+### MCP servers don't connect
+
+This is outside `p-replicator` scope — it's Claude Code config. Check:
+
+```bash
+cat .mcp.json                           # format correct?
+claude --debug                          # MCP errors in logs?
+```
+
+Statusline shows server count from `.mcp.json` regardless of working state.
+
+---
+
+## Performance
+
+### Statusline lags on every command
+
+**Cause:** very large `docs/` or filesystem trees.
+
+**Diagnose:**
+
+```bash
+time node .claude/hooks/statusline.cjs    # how many seconds?
+```
+
+Should be < 100ms. If > 1s, check `docs/` size:
+
+```bash
+du -sh docs/
+find docs/ -type f -name "*.md" | wc -l
+```
+
+**Workaround:** temporarily disable statusline by removing the
+`statusLine` field in `.claude/settings.json`.
+
+See `KNOWN_LIMITATIONS.md` item L6 — future enhancement: env var
+`STATUSLINE_PROFILE=1` for per-section measurements.
+
+---
+
+## Version incompatibilities
+
+### I'm on an old version. Should I upgrade?
+
+| Current → Target | What you get | Migration cost |
+|---|---|---|
+| 1.3.x → 1.5.0 | All pre-shipped commands + statusline + feature-branches + merge logic | Run `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` is safe (preserves) |
+| 1.4.2 → 1.4.3 | Orphan detection | First upgrade lacks baseline — re-run `init --force` to populate |
+| 1.4.3 → 1.5.0 | Statusline + --feature-branches | `update` or `init --force` |
+
+Full history — in [07_changelog.md](./07_changelog.md) or `CHANGELOG.md`
+(authoritative).
+
+---
+
+## When all else fails
+
+1. Read `KNOWN_LIMITATIONS.md` — might be a known limitation
+2. Run `verify` + `doctor` — collect exact output
+3. File issue: https://github.com/dzhechko/pu-unicorn-replicate/issues
+   include: version, `verify` output, repro steps

package/README/eng/07_changelog.md

@@ -0,0 +1,134 @@
+# 07. Changelog (concise)
+
+Per-release evolution. Full details — in `../../CHANGELOG.md` (authoritative).
+
+## v1.5.0 — 2026-05-07
+
+**Two features + 12 new tests.**
+
+- ✨ **Statusline dashboard** (RuFlo-style 6-line multi-line status bar) via
+  `templates/.claude/hooks/statusline.cjs`
+- ✨ **`--feature-branches` flag** for `/run` and `/go` (teaching/demo workflow:
+  each feature on its own branch `feature/{NNN}-{id}`)
+- 🆕 `state-update.cjs` — argv-driven helper for pipeline commands to publish progress
+- 🆕 Roadmap schema extended: `number` (auto-assigned), `branch` (populated when done)
+- 🆕 `--auto-merge` companion flag (off by default)
+- 📊 105 tests / 36 suites / 113 → 115 files in snapshot baseline
+
+## v1.4.3 — 2026-05-07
+
+**Orphan hook detection.**
+
+- 🐛 **Closed last v1.4.2 limitation:** `mergeSettingsJson` now cleans hooks
+  shipped previously but removed in newer template
+- 🆕 `manifest.shippedDefaults['settings.json']` — baseline for orphan detection
+- 🆕 `removeOrphanHooks(existing, oldTpl, newTpl)` helper
+- 🐛 **Bonus fix:** `update.js` now also uses merge logic (was a bug: blindly
+  overwrote settings.json)
+- 📊 93 tests, +8 from v1.4.2
+
+## v1.4.2 — 2026-05-06
+
+**3 v1.4.1 limitations resolved.**
+
+- 🐛 `init --force` now MERGES settings.json (preserves user customizations)
+- 🆕 `--reset-settings` flag for explicit nuclear-overwrite
+- 🐛 Stronger meta-test for `replicate.md` drift (multi-axis: verbs +
+  section-scope + list-style + allowlist)
+- 🆕 `doctor` checks `git on PATH` (Prerequisites section)
+- 📊 85 tests, +11 from v1.4.1
+
+## v1.4.1 — 2026-05-06
+
+**3 v1.4.0 limitations + 1 critical regression discovery.**
+
+- 🐛 **Cross-platform hooks:** replaced bash chains with 4 Node scripts
+- 🐛 **`verify.js` SSOT:** `kind: 'pre-shipped' | 'project-generated'` field
+  + 3 new project-generated groups
+- 🐛 **Meta-tests** for `replicate.md` ↔ `replicate-pipeline.md` consistency
+- 🐛 **Critical regression discovered + fixed:** `sync-templates.js` cleanDir
+  silently deleted pre-shipped files during `npm publish --dry-run`. Switched
+  to MERGE mode
+- 🆕 6th COMPONENTS group: `hooks` (4 cross-platform Node scripts)
+- 🆕 `getItemRelativePath()` helper
+- 📊 74 tests, +14 from v1.4.0
+
+## v1.4.0 — 2026-05-06
+
+**Major release — 9 pre-shipped commands + verify command.**
+
+- ✨ Closed root cause of pain: `/replicate` Phase 3 no longer tries to
+  generate generic commands. All 11 commands + 5 rules + settings.json + 4
+  hooks now pre-shipped via `init`
+- ✨ **9 new pre-shipped commands:** `/start`, `/plan`, `/feature`, `/go`,
+  `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
+- ✨ **3 new pre-shipped rules:** `git-workflow`, `insights-capture`,
+  `feature-lifecycle`
+- ✨ **Settings.json shipped** with hooks
+- ✨ **`verify` command** — replaces user's manual verification prompt
+- 🐛 5 sources of truth divergence unified via `utils.COMPONENTS.items`
+- 📊 60 tests, +8 from 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
+- 🐛 **`update.js` corrupted manifest** — captured project-generated files,
+  causing data loss on subsequent `remove`. Fixed by using
+  `getRelativePaths(templateClaude)` instead of `projectClaude`
+- 🐛 Bonus: `update` now removes orphan template files
+- 📊 52 tests, +7 from 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.
+
+---
+
+## Per-version migration
+
+| From → To | Command |
+|---|---|
+| 1.3.x → 1.5.0 | `npx @dzhechkov/p-replicator@1.5.0 init --force` (preserves customizations) |
+| Any → latest | `npx @dzhechkov/p-replicator@latest update` |
+| Full reset | `... init --force --reset-settings` (loses custom hooks) |
+
+After any upgrade — `verify` to confirm contract:
+
+```bash
+npx @dzhechkov/p-replicator verify
+```
+
+---
+
+## Patterns persisted in AQE memory
+
+Each significant improvement persisted as a 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`
+
+Each pattern contains: context, problem, solution, verification, tradeoffs,
+applied-to (version/file).
+
+---
+
+## Full CHANGELOG
+
+See `../../CHANGELOG.md` — authoritative source with full details, migration
+notes, breaking changes (none — all upgrades backward-compatible).

package/README/eng/README.md

@@ -0,0 +1,60 @@
+# @dzhechkov/p-replicator — Documentation
+
+Comprehensive docs for `@dzhechkov/p-replicator` — a toolkit for AI-assisted
+product development in Claude Code (Vibe Coding).
+
+## What it is
+
+`p-replicator` installs a ready-made `.claude/` toolkit into any project:
+**11 slash commands**, **10 skills**, **4 agents**, **5 rules**, **6 hook
+scripts**, and a `settings.json` with pre-configured hooks. The flagship
+`/replicate` command takes a project through a 5-phase pipeline (Discovery →
+Planning → Validation → Toolkit Generation → Finalize), generating SPARC
+documentation and project-specific artifacts.
+
+## Navigation
+
+| Section | Description |
+|---|---|
+| [01_quickstart.md](./01_quickstart.md) | Install, first run, verification |
+| [02_user_guide.md](./02_user_guide.md) | All commands and workflows with examples |
+| [03_admin_guide.md](./03_admin_guide.md) | Hooks, settings.json, statusline, insights |
+| [04_api_reference.md](./04_api_reference.md) | CLI flags, manifest/roadmap/state schemas |
+| [05_architecture.md](./05_architecture.md) | Architecture: pre-shipped vs generated, SSOT |
+| [06_troubleshooting.md](./06_troubleshooting.md) | Common issues and resolutions |
+| [07_changelog.md](./07_changelog.md) | Version history 1.3.x → 1.5.x |
+
+## Languages
+
+- 🇬🇧 [English documentation](./README.md) (you are here)
+- 🇷🇺 [Документация на русском](../ru/README.md)
+
+## Version
+
+`@dzhechkov/p-replicator@1.5.0` (latest stable). See full version history
+in `../../CHANGELOG.md` (authoritative source).
+
+## Quick start
+
+```bash
+cd your-project
+npx @dzhechkov/p-replicator init
+claude                              # open Claude Code
+/replicate "Your product description"
+```
+
+After `/replicate` completes, run `/run mvp` for autonomous feature build
+from roadmap, or `/start` to bootstrap the scaffold.
+
+## Related repositories
+
+- 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 documentation (in package)
+
+- `../../CHANGELOG.md` — version history
+- `../../KNOWN_LIMITATIONS.md` — open improvement items (7 entries)
+- `../../MULTIPLATFORM_ROADMAP.md` — Codex/OpenCode/KiloCode support roadmap
+- `../../README.md` — short user-facing intro