@dzhechkov/p-replicator 1.5.12 → 1.5.14

package/KNOWN_LIMITATIONS.md

@@ -0,0 +1,327 @@
+# Known Limitations
+
+Open limitations of `@dzhechkov/p-replicator` that are accepted trade-offs in
+the current version but warrant attention in future iterations. Each item
+lists severity, version introduced, proposed fix, and effort estimate.
+
+For *resolved* limitations, see [CHANGELOG.md](./CHANGELOG.md).
+
+---
+
+## Medium priority
+
+### M1. `--feature-branches` behavior tested only via documentation-presence
+
+- **Introduced:** v1.5.0
+- **Status:** open
+- **Severity:** Medium
+- **Tags:** testing, e2e, git-workflow
+
+**Why it's a limitation:**
+The flag's docs are validated by meta-tests (`/run.md` and `/go.md` mention
+`--feature-branches`, `feature/{NNN}-{id}` format, `--auto-merge`,
+`auto-stash`). But the actual git workflow (branch creation, push, roadmap
+update, optional merge, recovery from dirty tree) is **not** exercised in any
+test. Regression in the documented workflow would slip past the suite.
+
+**Proposed fix:**
+Add an e2e test that:
+1. Initializes a tmp project with `git init`
+2. Creates a fake `.claude/feature-roadmap.json` with 2-3 features
+3. Spawns Claude Code (or simulates the workflow with a stub) running
+   `/run mvp --feature-branches --auto-merge`
+4. Asserts: feature branches created with correct names, pushed (to local
+   bare remote), roadmap updated with `number`+`branch`, main contains merge
+   commits.
+
+**Effort:** Tier M (~3-4 hours). Requires git stub or real spawn of Claude
+Code which complicates CI portability. Could use `simple-git` library or
+shell out to git directly.
+
+**Workaround until fixed:** Manual smoke test in a real Claude Code session.
+
+---
+
+### M2. No formal `--from-docs` CLI flag for /replicate
+
+- **Introduced:** v1.5.1 (workflow documented but invocation is heuristic)
+- **Status:** open
+- **Severity:** Medium
+- **Tags:** cli, ergonomics, replicate-flow
+
+**Why it's a limitation:**
+The "starting from existing technical docs" workflow (added in v1.5.1 to all
+documentation surfaces — README.md root, RU/EN user guides, replicate.md spec,
+replicate-pipeline.md rule) is invoked via natural-language overrides in
+`/replicate` input ("use my docs in `<path>`, skip Phase 0"). There is no
+formal CLI flag like `/replicate --from-docs <path> --skip-discovery` that the
+LLM can detect deterministically. The trigger detection is heuristic — it works
+in practice but isn't easy to test or guarantee.
+
+**Proposed fix:**
+1. Extend `templates/.claude/commands/replicate.md` with explicit flag-parsing
+   instructions in the command's frontmatter (`argument-hint: --from-docs <path>`)
+2. Add deterministic flag-detection logic at the start of /replicate:
+   - Parse `--from-docs <path>` and `--skip-discovery` from the command input
+   - Set state-file fields: `entry_mode: "from-docs"`, `existing_docs_path: <path>`
+3. Document the formal flags in the user guide (RU + EN) Path A snippet
+4. Optionally — add a thin wrapper command `/replicate-from-docs <path>` that
+   delegates to `/replicate` with pre-set overrides
+5. Add a meta-test asserting that the documented flags are consistently mentioned
+   in spec + rule + user guides
+
+**Effort:** Tier S (~2-3 hours). Pure markdown spec + docs sync. No CLI code
+changes (the flag is parsed by the LLM, not by `bin/cli.js`).
+
+**Workaround until fixed:** Use natural-language pattern documented in
+`README/{ru,eng}/02_user_guide.md` "Starting from existing tech docs" / "Альтернативный вход".
+
+---
+
+### M3. `/feature` requires standard SPARC doc paths (no `--prd-path` flag)
+
+- **Introduced:** v1.5.2 (Mode 2 workflow formalized but doc paths are hardcoded)
+- **Status:** open
+- **Severity:** Medium
+- **Tags:** ergonomics, feature-flow, doc-paths, mode-2
+
+**Why it's a limitation:**
+The "Feature workflow in existing project" scenario (Mode 2, added in v1.5.2 to
+all documentation surfaces — README.md root, RU/EN quickstart + user guides,
+feature.md spec, feature-lifecycle.md rule) requires the user to have their PRD,
+Specification, and Architecture docs at standard SPARC paths (`docs/PRD.md`,
+`docs/Specification.md`, `docs/Architecture.md`). There are no `--prd-path`,
+`--spec-path`, or `--docs-dir` flags for `/feature`. Existing projects with
+docs at non-standard locations (e.g., `docs/product/PRD.md`,
+`documentation/architecture.md`) must rename files or create symlinks one-time.
+
+**Proposed fix:**
+1. Add `docPaths` config in `.p-replicator.json` schema:
+   ```json
+   {
+     "docPaths": {
+       "prd": "docs/product/PRD.md",
+       "specification": "docs/specs/main-spec.md",
+       "architecture": "docs/architecture/system.md"
+     }
+   }
+   ```
+2. `/feature` resolves paths via `docPaths.<slot>` (with fallback to standard
+   `docs/<Slot>.md` if config missing)
+3. `verify` validates all `docPaths` entries exist
+4. `init --doc-paths-from <config>` flag for one-shot config bootstrap from
+   existing project layout
+5. Update RU + EN user guides with the config example
+6. Add meta-test asserting docPaths resolution honored
+
+**Effort:** Tier S (~3-4 hours). Pure config + spec read changes; no CLI
+command code rewrites. Backward-compatible (default behavior preserved).
+
+**Workaround until fixed:** Rename or symlink existing docs to standard SPARC
+slot names. This is a one-time operation per project. Documented in
+`README/{ru,eng}/02_user_guide.md` "Feature workflow в существующем проекте (Mode 2)" /
+"Feature workflow in an existing project (Mode 2)".
+
+---
+
+## Low priority
+
+### L1. `shippedDefaults` baseline tracks only `settings.json`
+
+- **Introduced:** v1.4.3
+- **Status:** open
+- **Severity:** Low
+- **Tags:** orphan-detection, manifest-schema, generality
+
+**Why:**
+v1.4.3's `shippedDefaults` mechanism solves orphan detection only for
+`settings.json`. If a future version needs the same protection for another
+shipped JSON file (e.g., `.claude/feature-roadmap.json` defaults, or a new
+`.mcp.json` template) — the baseline tracking has to be extended.
+
+**Proposed fix:**
+Generalize `shippedDefaults` from a single-file snapshot to a multi-file map.
+`removeOrphanHooks` would become `removeOrphanFromConfig(existing, oldTpl,
+newTpl, configType)` with type-aware diff strategies (hooks for
+settings.json, items for roadmap, etc.).
+
+**Effort:** Tier S-M (~1-2 hours). Mostly schema generalization + tests.
+
+---
+
+### L2. Hook identity via `command` string is fragile
+
+- **Introduced:** v1.4.2 (`mergeSettingsJson`), v1.4.3 (`removeOrphanHooks`)
+- **Status:** open
+- **Severity:** Low
+- **Tags:** identity-model, settings-json, false-positives
+
+**Why:**
+Hook commands are compared by their `command` string for de-dup and orphan
+detection. If a template changes a hook's command string slightly (e.g., adds
+a flag like `--silent`), the old version is treated as orphan and the new as
+addition — usually correct. But if a user customized the command (e.g.,
+changed timeout from 10 to 30 — but command unchanged), they keep their
+customization (correct). Edge case: user TWEAKED the command (e.g., adjusted
+script path), then on upgrade the old command is removed AND the new
+command is added — the user's tweak is discarded.
+
+**Proposed fix (option A):** Add stable `_id` field to template hooks.
+Identity by id, not command-string. Pollutes settings.json schema slightly.
+
+**Proposed fix (option B):** Track per-hook ownership (template vs user) in
+manifest. More intrusive but cleaner.
+
+**Effort:** Tier M (~4 hours). Need careful migration for existing manifests.
+
+**Workaround:** User can re-customize after upgrade if their tweaks were lost.
+
+---
+
+### L3. No e2e tests for `update` + orphan detection (only for `init --force`)
+
+- **Introduced:** v1.4.3
+- **Status:** open
+- **Severity:** Low
+- **Tags:** testing, e2e, regression-risk
+
+**Why:**
+v1.4.3 added the same `mergeSettingsJson` + `removeOrphanHooks` pipeline to
+both `init.js` and `update.js`. E2E tests cover `init --force` thoroughly
+(orphan removed, user-added preserved, --reset-settings resets). Equivalent
+tests for `update` path don't exist — `update.js` is implicitly trusted
+because it uses the same helpers.
+
+**Proposed fix:**
+Add 3 e2e tests mirroring the v1.4.3 init e2e tests, but for `update`
+command. Same setup (init → mutate settings.json → modify template → call
+update), same assertions.
+
+**Effort:** Tier S (~30 min, copy-paste-adapt of existing init tests).
+
+---
+
+### L4. Validation score regex pattern catches only one format
+
+- **Introduced:** v1.5.0 (statusline.cjs)
+- **Status:** open
+- **Severity:** Low
+- **Tags:** statusline, parsing, fragility
+
+**Why:**
+`statusline.cjs` extracts validation score from `docs/validation-report.md`
+via regex: `(?:average\s+)?score[:\s]+(\d{1,3})(?:\s*\/\s*100)?`. This
+catches "Score: 78", "Average Score: 78/100", but if a future
+`requirements-validator` skill outputs a different format (e.g.,
+"Total: 78", "Final: 78%", or YAML-style `score: 78`), the parser misses
+and statusline shows no score badge.
+
+**Proposed fix:**
+Extend the regex with multiple patterns:
+```js
+const patterns = [
+  /(?:average\s+)?score[:\s]+(\d{1,3})/i,
+  /total[:\s]+(\d{1,3})\s*\/?\s*100/i,
+  /final[:\s]+(\d{1,3})/i,
+  /^score:\s*(\d{1,3})\s*$/im,
+];
+```
+Or formalize: `requirements-validator` skill outputs a machine-readable
+sidecar `docs/validation-summary.json` with `{score: N}`, parse that
+directly. More robust.
+
+**Effort:** Tier S (~30 min for regex extension, Tier M for sidecar).
+
+---
+
+### L5. State-file `.claude/.p-replicator-state.json` not auto-gitignored
+
+- **Introduced:** v1.5.0 (state-update.cjs + statusline.cjs)
+- **Status:** open
+- **Severity:** Low
+- **Tags:** gitignore, ephemeral-state, accidental-commit
+
+**Why:**
+The state-file is ephemeral — it tracks *current* command + phase + progress
+for live statusline display. It changes every few seconds during a pipeline
+run. If a user commits everything in `.claude/` (which is normal because
+that's the project's Claude Code config), the state-file gets committed too,
+then changes again, creating noisy diff churn.
+
+**Proposed fix (option A):** `init` appends `.claude/.p-replicator-state.json`
+to project's `.gitignore` if not already present. Less invasive: add to
+`/start.md` template the instruction "Add `.claude/.p-replicator-state.json`
+and `.claude/.last-test.json` to .gitignore".
+
+**Proposed fix (option B):** Move ephemeral state out of `.claude/` to a
+separate cache dir `.p-replicator-cache/` (which has its own gitignore
+expectation). Cleaner separation of project-config vs runtime-cache.
+
+**Effort:** Option A: Tier S (~15 min). Option B: Tier S-M (~1 hour, requires
+updating statusline.cjs paths).
+
+---
+
+### L6. Statusline render time not measured
+
+- **Introduced:** v1.5.0
+- **Status:** open
+- **Severity:** Low
+- **Tags:** performance, observability
+
+**Why:**
+The statusline runs on every Claude Code prompt. If filesystem operations
+get slow (very large `docs/` tree, network drives, etc.), the prompt
+visibly lags. There's no instrumentation to detect or report this. User
+notices "prompt is slow" without a clear signal that statusline is the
+culprit.
+
+**Proposed fix:**
+Add optional `STATUSLINE_PROFILE=1` env-var that prints elapsed time per
+section to stderr. Captured by Claude Code as debug output. Not visible by
+default — opt-in via `STATUSLINE_PROFILE=1 claude`.
+
+**Effort:** Tier S (~30 min, just `process.hrtime.bigint()` deltas around
+each parser).
+
+**Workaround:** None until measured. If render becomes slow, suspect
+statusline first; can disable by removing `statusLine` field from
+`.claude/settings.json`.
+
+---
+
+### L7. Statusline assumes 5 SPARC docs always required
+
+- **Introduced:** v1.5.0
+- **Status:** open
+- **Severity:** Low
+- **Tags:** statusline, hardcoded-list, generality
+
+**Why:**
+`statusline.cjs:parseSparcDocs()` has a hardcoded list of 11 expected SPARC
+docs. If `sparc-prd-mini` skill evolves to add a 12th doc or rename one,
+statusline shows incorrect "N/11". Same SSOT-divergence pattern as Fix #1
+fought.
+
+**Proposed fix:**
+Source the expected list from the `sparc-prd-mini` skill itself (e.g., its
+SKILL.md frontmatter or a `references/expected-outputs.json`). Statusline
+reads that at runtime.
+
+**Effort:** Tier M (~2 hours, requires schema decision in sparc-prd-mini
+side too).
+
+---
+
+## Summary
+
+| Priority | Count | Total effort estimate |
+|----------|-------|----------------------|
+| Medium   | 1     | ~3-4 hours |
+| Low      | 6     | ~6-8 hours |
+| **Total** | **7** | **~10-12 hours** |
+
+Pick the items that match current goals; each is independent and can be
+addressed in any order. The Medium-priority M1 (real git e2e for
+`--feature-branches`) gives the highest confidence boost for the v1.5.0
+teaching workflow if the package gets real classroom usage.

package/MULTIPLATFORM_ROADMAP.md

@@ -0,0 +1,239 @@
+# Multi-Platform Compatibility Roadmap
+
+**Status:** roadmap (not committed). Captured 2026-05-07 for future review.
+
+This document analyzes the cost/benefit of expanding `@dzhechkov/p-replicator`
+from Claude Code-only to also supporting **Codex CLI**, **OpenCode**, and
+**KiloCode**. Tracking the analysis here so we can return to the question
+when real demand for non-Claude platforms appears.
+
+---
+
+## Why this matters
+
+`p-replicator` ships a workflow toolkit (slash commands, skills, agents,
+rules, hooks, statusline) that currently targets Claude Code's config layout
+(`.claude/...`, `settings.json`). For teaching/demo use cases (the
+`--feature-branches` flag in v1.5.0), students using other AI coding tools
+hit a wall — they have to either install Claude Code or copy artifacts
+manually.
+
+The opportunity: 80%+ of the toolkit's *content* (markdown-based skills,
+commands, rules) is platform-neutral. Only delivery paths and a few unique
+features (hooks, statusline) need adapter logic.
+
+---
+
+## Compatibility matrix (concept → platform)
+
+| Concept | Claude Code | Codex CLI | OpenCode (sst) | KiloCode (VS Code ext.) |
+|---|---|---|---|---|
+| **Slash commands** | `.claude/commands/<name>.md` | `~/.codex/prompts/<name>.md` (global) or per-project | `opencode.json` commands array | `.kilocode/commands/<name>.md` |
+| **Project context** | `CLAUDE.md` | `AGENTS.md` (canonical) | `AGENTS.md` or `opencode.json` instructions | `.kilocode/rules/` |
+| **Skills (composable, `view()`)** | `.claude/skills/<name>/SKILL.md` | ❌ none — must inline | ❌ none — folder of refs | ⚠️ via custom modes |
+| **Subagents** | `.claude/agents/<name>.md` + Task tool | Subtasks (different API) | Modes/agents in config | Custom modes |
+| **Rules** | `.claude/rules/<name>.md` | Sections in AGENTS.md | `opencode.json:rules` | `.kilocode/rules/<name>.md` |
+| **Hooks (SessionStart, Stop)** | `settings.json:hooks` | ❌ none (only approval policies) | ⚠️ limited | ❌ only VS Code event API |
+| **Statusline** | `settings.json:statusLine` | ❌ none (text CLI) | ⚠️ TUI status (different model) | ❌ requires VS Code ext. API |
+| **MCP servers** | `.mcp.json` | `~/.codex/config.toml` `[mcp_servers.X]` | `opencode.json:mcp` | `.kilocode/mcp.json` |
+| **Manifest tracking** | `.p-replicator.json` | universal — any project | universal | universal |
+
+### Universality verdict
+
+- ✅ **Universal (~80-100%):** slash commands, rules, MCP, manifest, project context
+- ⚠️ **Lossy (~50-60%):** skills (require inline-compilation), subagents (different runtime models)
+- ❌ **Claude-only:** hooks, statusline (graceful degradation needed)
+
+---
+
+## Three levels of approach
+
+### Level 1 — Concept-portable, manual copy
+
+**Effort:** Tier M, **~6-8 hours**.
+
+**What changes:**
+- Remove `.claude/skills/<X>/SKILL.md` paths from command markdown
+- Replace `view("/mnt/skills/...")` with platform-neutral "load skill X"
+- Hooks/statusline remain Claude-only (documented as advanced features)
+- Add `compatibility/MANUAL_INSTALL.md` with per-platform copy instructions
+
+**Result:** ~70% functionality preserved on any platform via manual file copy.
+Lost: hooks (auto-commit), statusline.
+
+### Level 2 — Adapter pattern with `init --target <platform>`
+
+**Effort:** Tier L, **~16-30 hours total** (per-platform varies).
+
+Mirror existing `product-keysarium-2026/lib/platform-adapters.md` pattern
+(`/init-platform --platform <name>`).
+
+```
+src/adapters/
+├── claude-code.js   # default (current behavior)
+├── codex.js         # → ~/.codex/prompts/ + AGENTS.md
+├── opencode.js      # → opencode.json
+└── kilocode.js      # → .kilocode/
+```
+
+**Each adapter implements:**
+- `getPaths()` — where each artifact type belongs on this platform
+- `translateCommand(content)` — `$ARGUMENTS` → platform syntax
+- `installCommand|Rule|Skill|Agent` — with path-mapping
+- `installSettings|Hooks|Statusline` — skip on platforms without them (graceful)
+
+**Per-platform effort:**
+- Codex: ~8-10h (well-documented, AGENTS.md + prompts/, MCP) — closest model
+- OpenCode: ~8-10h (`opencode.json` schema, modes API)
+- KiloCode: ~12-20h (VS Code paradigm, may need companion extension)
+
+**Result:** 80-90% feature parity per platform. Hooks/statusline still degraded.
+
+### Level 3 — Full feature parity with workaround logic
+
+**Effort:** Tier XL, **multi-week project**.
+
+Beyond Level 2 — adapt logic for platform-specific capabilities:
+- Codex: bake auto-commit into commands themselves (no SessionStart/Stop)
+- OpenCode: use TUI status API for statusline
+- KiloCode: companion VS Code extension with TreeView progress, status bar item
+
+**Verdict:** Premature optimization for current scope. Skip until concrete demand.
+
+---
+
+## Per-feature breakdown — what's worth adapting
+
+| Feature | Universal | Adapt effort | Recommendation |
+|---|---|---|---|
+| `/replicate` pipeline | ✅ logic universal | path-translate commands | **Yes** — primary value |
+| `/run`, `/go`, `/next` workflow | ✅ universal | translate `$ARGUMENTS` | **Yes** |
+| `/feature`, `/plan` SPARC lifecycle | ✅ universal | inline skill content | **Yes** |
+| `/myinsights`, `/docs`, `/harvest`, `/start`, `/deploy` | ✅ universal | path-translate | **Yes** |
+| 10 skills (sparc-prd-mini, etc.) | ⚠️ Claude-specific composition | inline-compile into commands | **Compromise** — sacrifice runtime-loading |
+| 4 pre-shipped agents | ⚠️ Claude Task-tool specific | translate to platform sub-agents | **Yes if platform supports** |
+| 5 rules | ✅ universal markdown | path-translate | **Yes** |
+| Hooks (SessionStart insights, Stop autocommit) | ❌ Claude-only | bake into commands as instructions | **Compromise** — degraded UX |
+| Statusline dashboard | ❌ Claude-only | optional `progress.md` file? | **Skip** — Claude-exclusive feature |
+| `verify` CLI command | ✅ universal | works as-is | **Yes** (already works) |
+| `feature-roadmap.json` + `--feature-branches` | ✅ git-based | works as-is | **Yes** |
+| MCP server config | ✅ universal | path-translate config file | **Yes** |
+
+---
+
+## Hidden complexities
+
+1. **Slash command argument syntax differs:**
+   - Claude: `$ARGUMENTS`, `$ARG1`
+   - Codex: `{{arg}}` or appended params
+   - OpenCode: configurable
+   - **Adapter responsibility:** substitution at install time
+
+2. **Skill composition (`view()` syntax):**
+   - Claude runtime resolves `view(.claude/skills/X/SKILL.md)` dynamically
+   - On other platforms, SKILL.md content must be **inlined** into command at install time
+   - Compile step: recursively replace `view()` references with content
+   - Complexity: cross-skill dependencies (cc-toolkit-generator-enhanced → 9 modules), deep recursion
+
+3. **Subagent semantics:**
+   - Claude: `Task` tool spawns parallel sub-conversations with their own model
+   - Codex: sub-tasks (similar but different API)
+   - Some platforms: parallel → sequential fallback
+   - Performance hit on large pipelines
+
+4. **Settings schema differences:**
+   - Claude: JSON schema X
+   - OpenCode: JSON schema Y
+   - Codex: TOML
+   - Adapter generates platform-specific config from common abstract spec
+
+5. **MCP config location/format:**
+   - All 4 support MCP, but file/format differ (JSON vs TOML, project-local vs global)
+   - Translatable, but requires per-platform writer
+
+---
+
+## Recommended phased path
+
+### Phase A — Documentation only (Tier S, ~2h)
+
+Add a "Compatibility" section to `README.md` and `CHANGELOG.md`:
+
+> «p-replicator v1.5.0 is designed primarily for Claude Code. Other platforms
+> (Codex, OpenCode, KiloCode) are supported via Level 1 manual copy. Full
+> per-platform adapters are tracked in `MULTIPLATFORM_ROADMAP.md`.»
+
+Honest communication; sets expectations.
+
+### Phase B — Level 1 adaptation (Tier M, ~6-8h)
+
+Make commands platform-neutral. Add `compatibility/` directory with
+per-platform manual install guides. Optional `init --target <platform>`
+flag that just prints copy instructions.
+
+### Phase C — Level 2 per-platform adapter (Tier L, ~10-20h per platform)
+
+Implement adapter when concrete user demand for that platform appears.
+Recommended order: **Codex first** (closest model, biggest user base),
+then OpenCode, then KiloCode (different paradigm).
+
+---
+
+## Most-bang-for-buck: Codex first
+
+If only one adapter ever gets built, **Codex** is the highest-value pick:
+- Closest model to Claude Code (CLI agent + AGENTS.md + slash prompts + MCP)
+- Largest non-Claude user base
+- Cleanest translation (skills → AGENTS.md compilation; commands → prompts/; MCP straightforward)
+- Estimated 85% feature parity post-adapter
+
+OpenCode and KiloCode follow as demand appears.
+
+---
+
+## Effort matrix
+
+| Approach | Time | Result |
+|---|---|---|
+| **Phase A** (documentation) | **2h** | Honest user communication |
+| **Phase B** (Level 1 manual-copy) | **+6-8h** | ~70% functionality on any platform via copy |
+| **Phase C — Codex adapter** | **+10-14h** | Native install on Codex with ~85% functionality |
+| **Phase C — OpenCode adapter** | **+10-14h** | Native install on OpenCode |
+| **Phase C — KiloCode adapter** | **+15-20h** (different paradigm, harder) | Native install on KiloCode |
+| **Full Phase A+B+C for all 3 platforms** | **~50-60h** | Full multi-platform v2.0 |
+
+---
+
+## Reuse from product-keysarium-2026
+
+The parent monorepo already has prior art:
+- `lib/platform-adapters.md` — adapter registry concept
+- `lib/platform-templates/{cursor,opencode,copilot}.md` — example templates
+- `/init-platform --platform <name>` slash command in `.claude/commands/`
+
+When implementing Phase B/C, **reuse these patterns** rather than designing
+from scratch. The keysarium pattern already establishes conventions for
+multi-platform support across the dz-* package family.
+
+---
+
+## Open decisions for future review
+
+1. **Which platforms actually needed?** All 4 or just Claude+Codex?
+2. **Depth of compatibility?** Manual-copy-friendly (Phase B) vs `init --target X` (Phase C) vs full feature parity (Level 3)?
+3. **Timing:** start with Phase A docs only, or build Phase B+C immediately?
+4. **Scope:** v2.0 milestone or incremental (v1.6 = Phase A+B, v1.7 = Codex adapter, etc.)?
+5. **Reuse strategy:** copy keysarium-2026's adapter pattern verbatim or design lighter version?
+
+---
+
+## Companion files
+
+- `KNOWN_LIMITATIONS.md` — open issues with current Claude-only implementation (7 items)
+- `CHANGELOG.md` — version history
+- `README.md` — user-facing docs
+
+---
+
+*Last updated: 2026-05-07. Re-evaluate when concrete demand for non-Claude
+platform support emerges (e.g., classroom usage with mixed-tool students).*

package/README/eng/06_troubleshooting.md

@@ -349,5 +349,5 @@ Full history — in [07_changelog.md](./07_changelog.md) or `CHANGELOG.md`
 
 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
+3. File issue: https://github.com/djd1m/dz-harness-hub/issues
    include: version, `verify` output, repro steps

package/README/eng/07_changelog.md

@@ -2,6 +2,63 @@
 
 Per-release evolution. Full details — in `../../CHANGELOG.md` (authoritative).
 
+## v1.5.14 — 2026-07-28
+
+**Docs & packaging fixes** (package-verification findings; no runtime code changes).
+
+- 📚 Changelog gap v1.5.5–v1.5.13 closed in `CHANGELOG.md` + README highlights
+- 📦 `CHANGELOG.md` / `KNOWN_LIMITATIONS.md` / `MULTIPLATFORM_ROADMAP.md` /
+  `tests/` now ship in the tarball (doc links resolve; `npm test` works in the
+  installed package — MEASURED: 105/105 in the unpacked pack)
+- 🔗 GitHub links → monorepo `github.com/djd1m/dz-harness-hub`
+  (`packages/@dzhechkov/p-replicator`)
+- 🔢 npm description skill char-count 194K+ → 880K+ (MEASURED:
+  `find templates/.claude/skills -type f -exec cat {} + | wc -c` → 880,679)
+
+## v1.5.13 — 2026-07-10
+
+- 🐛 `brutal-honesty-review/schemas/output.json`: `trustTier` `const: 3` →
+  range 1–3
+
+## v1.5.11 / v1.5.12 — 2026-07-06
+
+- ✨ `brutal-honesty-review` gained `evals/`, `schemas/output.json`,
+  `scripts/validate-config.json` (baseline-heal); v1.5.12 = version-sync only
+
+## v1.5.9 / v1.5.10 — 2026-07-06
+
+- 🔒 `goap-research-ed25519` honesty rewrite: Ed25519 = provenance +
+  tamper-evidence under pinned issuer keys, NOT anti-hallucination (net
+  −1,696 lines — MEASURED: `git diff --stat 9f18ec43 41ec8d36`)
+- 🐛 `remove --dry-run` no longer deletes the manifest; `remove` keeps the
+  manifest when some files fail to delete; v1.5.10 = version-sync only
+
+## v1.5.8 — 2026-06-29
+
+- 🆕 `trust_tier` frontmatter on vendored skills + ADR-0001 `sources.json`
+  provenance record + optional `clone-website` UI-replication section
+  (MEASURED: `git diff c9225e8f 9f18ec43 -- packages/@dzhechkov/p-replicator`)
+
+## v1.5.7 — 2026-06-16
+
+- 🐛 Unknown options / unexpected CLI arguments now exit 1
+- 🐛 `init` manifest tracks the TEMPLATE source, never a destination scan
+
+## v1.5.5 / v1.5.6 — 2026-06-11
+
+- 📦 First monorepo releases (`dz-harness-hub`); destructive `prepublishOnly`
+  sync hook removed; `explore` skill gained `trust_tier` frontmatter
+
+## v1.5.4 — 2026-05-13
+
+- 🐛 settings.json `$schema` URL → `json.schemastore.org` variant (the `www.`
+  variant made Claude Code skip the whole settings file)
+
+## v1.5.1 – v1.5.3 — 2026-05-07
+
+- 📚 Docs-only patches: existing-docs workflow (v1.5.1), Mode 2 formalized
+  (v1.5.2), npm README expanded ~14.6 kB → ~50 kB (v1.5.3)
+
 ## v1.5.0 — 2026-05-07
 
 **Two features + 12 new tests.**

package/README/eng/README.md

@@ -49,8 +49,8 @@ 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
+- GitHub: https://github.com/djd1m/dz-harness-hub/tree/main/packages/@dzhechkov/p-replicator
+- Issues: https://github.com/djd1m/dz-harness-hub/issues
 
 ## Companion documentation (in package)
 

package/README/ru/06_troubleshooting.md

@@ -351,5 +351,5 @@ find docs/ -type f -name "*.md" | wc -l
 
 1. Прочитайте `KNOWN_LIMITATIONS.md` — может это известное ограничение
 2. Запустите `verify` + `doctor` — соберите exact output
-3. Issue: https://github.com/dzhechko/pu-unicorn-replicate/issues
+3. Issue: https://github.com/djd1m/dz-harness-hub/issues
    приложите версию, output `verify`, шаги воспроизведения