@dzhechkov/p-replicator 1.5.18 → 1.9.0

package/README.md

@@ -101,7 +101,7 @@
 
 ## 📖 What is p-replicator?
 
-`@dzhechkov/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 and a multi-line statusline dashboard.
+`@dzhechkov/p-replicator` installs a ready-made `.claude/` toolkit into any project: **11 slash commands**, **10 skills**, **4 agents**, **6 rules**, **9 hook scripts**, and a `settings.json` with pre-configured hooks and a multi-line statusline dashboard.
 
 The flagship `/replicate` command takes a project through a **5-phase pipeline**:
 
@@ -289,8 +289,8 @@ This creates:
 | **Skills** | 10 | 92 files (880K+ chars — MEASURED via `wc -c` over `templates/.claude/skills`: 880,679). Modular architecture: foundation → composite → master orchestrator |
 | **Commands** | 11 | `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy` |
 | **Agents** | 4 | `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator` |
-| **Rules** | 5 | `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle` |
-| **Hooks** | 6 | `session-insights`, `autocommit-{roadmap,insights,plans}`, `statusline`, `state-update` (cross-platform Node) |
+| **Rules** | 6 | `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`, `docker-ports` |
+| **Hooks** | 9 | `session-insights`, `autocommit-{roadmap,insights,plans}`, `statusline`, `state-update`, `check-ports`, `check-growth-trace`, `check-docs-complete` (cross-platform Node) |
 | **Settings** | 1 | `settings.json` with statusLine + SessionStart + Stop hooks pre-configured |
 
 After running `/replicate`, the toolkit also generates **project-specific** artifacts:
@@ -306,6 +306,108 @@ After running `/replicate`, the toolkit also generates **project-specific** arti
 
 ---
 
+## 📈 Growth: from analysis to obligation
+
+Phase 0's M5 module used to end as analysis — and the analysis had nowhere to go, because the Product
+Discovery Brief was never written to disk at all. Since 1.7.0:
+
+- Phase 0 writes `docs/product-discovery-brief.md`.
+- M5 emits a **Growth Requirements Seed**: `FR-GROWTH-nnn` DRAFT obligations, each naming the
+  analysis block it came from and carrying that block's confidence verbatim.
+- Growth type is **two independent choices** — a go-to-market MOTION and a growth LOOP. The old
+  single list forced one pick across both, which made "sales-led company running a referral loop"
+  unsayable. `No loop` is a real answer and skips the loop-only output.
+- A **compliance checklist** runs before a technique becomes a requirement. It names the norm and
+  where to check it, never an amount or a statute — those go stale and are jurisdiction-specific.
+  A `no` answer blocks that requirement's promotion.
+- Phase 2's validator gains a **conditional** `Growth Traceability` criterion: `+5` traced, `+0` not
+  applicable, `-10` applicable but dropped. It scores outside the 100-point table, and a project with
+  no acquisition objective — or one that never ran Phase 0 — scores `+0`, never a penalty.
+
+What none of this proves: that anything was built, or that copying a competitor's move is lawful.
+
+## 🔎 The three deliberate checks
+
+Six of the nine hook scripts run themselves. Three do not: they are utilities you invoke when you want
+an answer, and they are wired to no event on purpose. A hook of this package is **non-blocking by
+contract** — it can print, never refuse — so a check that must be able to say "no" cannot be one.
+
+Both answer with **three** exit codes, and the third is the one that matters:
+
+| Code | Meaning |
+|:---:|---|
+| `0` | the rule holds |
+| `1` | the rule is violated — the offender is named |
+| `2` | **the check did not run** — it could not look, and says so |
+
+A checker that answers "clean" when it could not look turns an unknown into a reassurance. That is
+why a missing config, a missing docker, or a missing brief is `2` and never `0`.
+
+### `check-ports.cjs` — no database faces the internet
+
+```bash
+node .claude/hooks/check-ports.cjs .
+```
+
+```
+❌ Правило №0 нарушено (.claude/rules/docker-ports.md):
+   • db: порт 5432 → 5432 (без адреса — значит все интерфейсы) — хранилище опубликовано наружу.
+     Убрать ports: целиком, либо привязать к 127.0.0.1
+```
+
+Reads the normalised config (`docker compose config`), so the short port form and `extends` are
+already resolved. Catches `network_mode: host` and services published beside a reverse-proxy too.
+A loopback bind (`127.0.0.1:` or `[::1]:`) is legal and passes — that exception is part of the rule.
+
+**When to run it:** after writing or editing `docker-compose.yml`, and before any deploy.
+
+### `check-docs-complete.cjs` — the cheap question, before the swarm
+
+```bash
+node .claude/hooks/check-docs-complete.cjs .
+```
+
+```
+❌ документы Фазы 1 не готовы к валидации (1):
+   • PRD.md: пуст или почти пуст (5 симв., порог 200)
+   Рой валидации запускать рано: он потратит агентов на то, что видно отсюда.
+```
+
+Phase 2 launches a swarm of validation agents over whatever Phase 1 produced. Existence, emptiness
+and unfilled placeholders are decidable by forty lines of code — this asks them first, so the swarm
+is spent on testability and completeness rather than on discovering an empty file.
+
+`docs/ADR.md` and `docs/C4_Diagrams.md` stay optional, as `/replicate` itself declares them. A
+markdown link is not a placeholder.
+
+**When to run it:** at the Phase 1 → Phase 2 boundary. `/replicate` now runs it there for you.
+
+**What it does NOT prove:** that the documents are correct. That is what the swarm is for.
+
+### `check-growth-trace.cjs` — the growth analysis was not analysed and dropped
+
+```bash
+node .claude/hooks/check-growth-trace.cjs .
+```
+
+```
+❌ часть требований по росту потеряна (1 из 2):
+   • FR-GROWTH-002
+   Каждое надо либо перенести в docs/Specification.md, либо отклонить С ПРИЧИНОЙ — молча уронить нельзя.
+```
+
+Phase 0's M5 module emits a `Growth Requirements Seed` table of `FR-GROWTH-nnn` draft obligations
+into `docs/product-discovery-brief.md`. This asks whether they survived into `docs/Specification.md`.
+A conscious rejection **with a reason written down** passes; a silent drop does not.
+
+`docs/product-discovery-brief.md` absent is `2`, not `0` — it means Phase 0 never ran (the
+`--from-docs` entry skips it), which is not the same as having nothing to trace.
+
+**When to run it:** at the Phase 1 → Phase 2 boundary, before the validation pass.
+
+**What it does NOT prove:** that anything was built, or that copying a competitor's growth move is
+lawful. It proves an obligation was carried forward, nothing more.
+
 ## ✅ Verify the install
 
 After `/replicate`, run:
@@ -316,7 +418,7 @@ npx @dzhechkov/p-replicator verify
 
 The command checks:
 
-- **Pre-shipped contract** (must-have): 10 skills + 11 commands + 4 agents + 5 rules + settings.json + 6 hooks
+- **Pre-shipped contract** (must-have): 10 skills + 11 commands + 4 agents + 6 rules + settings.json + 9 hooks
 - **Post-/replicate hints** (advisory): CLAUDE.md, project-specific agents, feature-roadmap.json, security rules, etc.
 
 **Exit codes:**
@@ -360,6 +462,14 @@ Generates 11 standardized documents in `docs/`:
 | `C4_Diagrams.md` | Context / container / component |
 | `ADR.md` | Architecture Decision Records |
 
+> **ADR detection reads BOTH storage shapes.** `/replicate` writes every decision into one
+> `docs/ADR.md`, while an idea2prd-manual project keeps a `docs/adr/*.md` directory. Since 1.5.19 the
+> toolkit generator's scanner normalizes both into one decision list, so the ADR-driven parts of the
+> generated toolkit (architect skill weighting, security boosts, tech-stack extraction, CLAUDE.md key
+> decisions) work for `/replicate` projects too. Before 1.5.19 the scanner required a directory of
+> more than five files, so for every `/replicate` project the flag was unreachable and those parts
+> silently produced nothing.
+
 Skill: `sparc-prd-mini` (internally chains explore + research + solve sub-phases).
 
 ### Phase 2 — Validation (5-agent swarm)
@@ -664,7 +774,7 @@ P-Replicator V1.5.x ● user │ Sonnet 4.7
 🚀 Pipeline   /<cmd> ▓▓▓░░░░ 50%  │ Phase: VALIDATE (2/4)  │ Last: /replicate
 🎯 Roadmap    [●●●○○○○○] mvp 3/8   │ Done 5/12  │ ▶ auth-jwt  │ Domain: banking
 📊 SPARC      ●11/11  │ 🟢 78/100  │ Plans ●3  │ ADRs ●2  │ Harvest 2026-05-05
-🛠️ Toolkit    Skills ●10/10 │ Cmds ●11/11 │ Agents ●4+3 │ Rules ●5+2 │ Hooks ●6/6
+🛠️ Toolkit    Skills ●10/10 │ Cmds ●11/11 │ Agents ●4+3 │ Rules ●6+2 │ Hooks ●7/7
 💡 Insights   ●12 (2026-05-06) │ Tests 85/85 ✓ │ MCP ●1/1 │ Settings ✓ │ 🧬 Keysarium ✓
 ```
 
@@ -734,7 +844,7 @@ All 4 autocommit scripts use `execFileSync('git', [...])` (no shell pipes, no `2
 Updated via `state-update.cjs`:
 
 ```bash
-node .claude/hooks/state-update.cjs \
+node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/state-update.cjs" \
   --command /feature \
   --phase VALIDATE \
   --index 2 \
@@ -880,14 +990,14 @@ Default structure after `init`:
   "_comment": "Default hooks + statusline shipped by @dzhechkov/p-replicator init.",
   "statusLine": {
     "type": "command",
-    "command": "node .claude/hooks/statusline.cjs"
+    "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/statusline.cjs\""
   },
   "hooks": {
     "SessionStart": [
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "node .claude/hooks/session-insights.cjs", "timeout": 5 }
+          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/session-insights.cjs\"", "timeout": 5 }
         ]
       }
     ],
@@ -895,9 +1005,9 @@ Default structure after `init`:
       {
         "matcher": "*",
         "hooks": [
-          { "type": "command", "command": "node .claude/hooks/autocommit-roadmap.cjs", "timeout": 10 },
-          { "type": "command", "command": "node .claude/hooks/autocommit-insights.cjs", "timeout": 10 },
-          { "type": "command", "command": "node .claude/hooks/autocommit-plans.cjs", "timeout": 10 }
+          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/autocommit-roadmap.cjs\"", "timeout": 10 },
+          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/autocommit-insights.cjs\"", "timeout": 10 },
+          { "type": "command", "command": "node \"${CLAUDE_PROJECT_DIR}/.claude/hooks/autocommit-plans.cjs\"", "timeout": 10 }
         ]
       }
     ]
@@ -905,6 +1015,19 @@ Default structure after `init`:
 }
 ```
 
+**Why `${CLAUDE_PROJECT_DIR}` and not a relative path:** a relative path resolves against the process
+working directory, which drifts — one `cd` inside a tool call moves it for the rest of the session, and
+the hook then dies with `MODULE_NOT_FOUND`. Because hooks are non-blocking, the session continues and
+your roadmap silently stops being committed. Claude Code sets `CLAUDE_PROJECT_DIR` to the project root
+and rewrites this exact braced form for PowerShell, so it works on every platform.
+
+The hook scripts anchor their DATA the same way, and fall back to their own location
+(`__dirname/../..`) when the variable is absent — so a hand-run works too. That fallback is why the
+shell examples elsewhere in this README use `${CLAUDE_PROJECT_DIR:-.}`: in a plain terminal the
+variable is unset, and `:-.` keeps the example working. Do **not** use the `:-.` form inside
+`settings.json` — Claude Code's PowerShell rewrite matches only the bare `${CLAUDE_PROJECT_DIR}`
+token, so `:-.` would leave a POSIX-only construct in a file that must work on every platform.
+
 **Customization:** add new hooks or event types — preserved on `init --force` or `update` thanks to merge logic.
 
 **Disable individual default hooks:** delete from `settings.json` after `init`. The deletion is preserved on next `update` (orphan detection only removes hooks **previously shipped** but absent in **new** template — your manual deletion is a user customization).
@@ -1012,13 +1135,13 @@ Checks:
 3. Script runs directly:
 
 ```bash
-node .claude/hooks/statusline.cjs
+node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/statusline.cjs"
 ```
 
 Should print 6 lines of ANSI output. If it errors:
 
 ```bash
-node .claude/hooks/statusline.cjs 2>&1
+node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/statusline.cjs" 2>&1
 ```
 
 Likely cause: corrupt JSON or missing `.p-replicator.json`.
@@ -1038,7 +1161,7 @@ git rev-parse --git-dir
 Debug a specific hook:
 
 ```bash
-node .claude/hooks/autocommit-roadmap.cjs
+node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/autocommit-roadmap.cjs"
 echo "Exit: $?"
 git log -1 --format="%s"
 ```
@@ -1103,7 +1226,7 @@ Checks:
 1. `.claude/insights/index.md` exists with entries?
 2. Hook works:
    ```bash
-   node .claude/hooks/session-insights.cjs    # should print recent insights
+   node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/session-insights.cjs"    # should print recent insights
    ```
 3. SessionStart hook configured in `settings.json`?
 
@@ -1112,7 +1235,7 @@ If all 3 OK but still nothing — Claude Code may cache. Restart `claude`.
 ### Statusline lags on every command
 
 ```bash
-time node .claude/hooks/statusline.cjs    # how many seconds?
+time node "${CLAUDE_PROJECT_DIR:-.}/.claude/hooks/statusline.cjs"    # how many seconds?
 ```
 
 Should be < 100ms. If > 1s, check `docs/` size:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dzhechkov/p-replicator",
-  "version": "1.5.18",
+  "version": "1.9.0",
   "description": "P-Replicator — Claude Code toolkit for AI-assisted product development (Vibe Coding). Full /replicate pipeline, 10 modular skills (880K+ chars), /harvest knowledge extraction, swarm agents, quality gates, security patterns, cross-project learning.",
   "main": "src/cli.js",
   "bin": {
@@ -18,6 +18,15 @@
     ".dz-manifest.json",
     "sbom.json"
   ],
+  "scripts": {
+    "prepublishOnly": "node --test tests/snapshot/templates.test.js && node ../../../scripts/prepublish-gate.mjs",
+    "test": "node --test tests/unit/utils.test.js tests/unit/adr-scanner-contract.test.js tests/unit/sparc-reconciliation.test.js tests/unit/pipeline-file-ownership.test.js tests/unit/validation-gate-teeth.test.js tests/unit/hooks-project-anchored.test.js tests/unit/statusline-two-roots.test.js tests/unit/external-dependency-check.test.js tests/unit/spec-pseudocode-traceability.test.js tests/unit/sync-templates-guard.test.js tests/unit/db-port-rule.test.js tests/unit/roadmap-one-schema.test.js tests/unit/hooks-report-failures.test.js tests/unit/growth-module-b2b-gate.test.js tests/unit/detect-parse-anchor.test.js tests/unit/statusline-honest-labels.test.js tests/unit/autocommit-deletion.test.js tests/unit/check-ports.test.js tests/unit/adr-decision-coverage.test.js tests/unit/growth-requirements-bridge.test.js tests/unit/check-growth-trace.test.js tests/unit/growth-gate-conditional.test.js tests/unit/module-copy-identity.test.js tests/unit/growth-axes-and-compliance.test.js tests/unit/skill-paths-prebaked.test.js tests/unit/check-docs-complete.test.js tests/e2e/lifecycle.test.js tests/snapshot/templates.test.js",
+    "test:unit": "node --test tests/unit/utils.test.js tests/unit/adr-scanner-contract.test.js tests/unit/sparc-reconciliation.test.js tests/unit/pipeline-file-ownership.test.js tests/unit/validation-gate-teeth.test.js tests/unit/hooks-project-anchored.test.js tests/unit/statusline-two-roots.test.js tests/unit/external-dependency-check.test.js tests/unit/spec-pseudocode-traceability.test.js tests/unit/sync-templates-guard.test.js tests/unit/db-port-rule.test.js tests/unit/roadmap-one-schema.test.js tests/unit/hooks-report-failures.test.js tests/unit/growth-module-b2b-gate.test.js tests/unit/detect-parse-anchor.test.js tests/unit/statusline-honest-labels.test.js tests/unit/autocommit-deletion.test.js tests/unit/check-ports.test.js tests/unit/adr-decision-coverage.test.js tests/unit/growth-requirements-bridge.test.js tests/unit/check-growth-trace.test.js tests/unit/growth-gate-conditional.test.js tests/unit/module-copy-identity.test.js tests/unit/growth-axes-and-compliance.test.js tests/unit/skill-paths-prebaked.test.js tests/unit/check-docs-complete.test.js",
+    "test:e2e": "node --test tests/e2e/lifecycle.test.js",
+    "test:snapshot": "node --test tests/snapshot/templates.test.js",
+    "test:doctor": "node bin/cli.js doctor",
+    "snapshot:baseline": "node tests/snapshot/update-baseline.js"
+  },
   "keywords": [
     "claude",
     "claude-code",
@@ -70,13 +79,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "test": "node --test tests/unit/utils.test.js tests/e2e/lifecycle.test.js tests/snapshot/templates.test.js",
-    "test:unit": "node --test tests/unit/utils.test.js",
-    "test:e2e": "node --test tests/e2e/lifecycle.test.js",
-    "test:snapshot": "node --test tests/snapshot/templates.test.js",
-    "test:doctor": "node bin/cli.js doctor",
-    "snapshot:baseline": "node tests/snapshot/update-baseline.js"
   }
-}
+}