@dzhechkov/p-replicator 1.10.4 → 1.13.1

package/templates/.claude/agents/product-discoverer.md

@@ -46,8 +46,46 @@ Product Discovery Brief — structured markdown passed as pre-filled context to
 
 ### Key Insights for PRD
 [Top 3-5 insights that should inform product planning]
+
+## Манифест передачи
+
+**Фаза 0 выполнена:** да
+**Проверка манифеста:** ВЫПОЛНЕНА
+**Причина:** —
+
+| Выход | Идентификатор | Модуль |
+|---|---|---|
+| [what this run actually produced] | PD-INSIGHT-001 | M5 |
 ```
 
+### The manifest is REQUIRED, and it is the last thing written
+
+The brief's six sections are passed onward through a CLOSED list of four fields
+(`target_segments`, `key_competitors`, `differentiation`, `monetization`). Two of the six therefore
+have no field at all — «Key Insights for PRD» has none, and «Growth Channels» travels only through
+the separate `FR-GROWTH` seed. The artifact is written, it is on disk, and the next phase has no
+input through which it could reach a decision: «used» and «silently dropped» look identical from
+every side, because nobody is obliged to answer by list.
+
+The manifest is that list. Three rules, and each of them is what makes it checkable rather than
+ceremonial:
+
+1. **Only ENUMERABLE outputs of the REAL run**, each with a stable identifier `PD-WORD-nnn`
+   (uppercase, three digits, never reused). Free prose cannot be answered by list, and answering by
+   list is the entire cure.
+2. **A module that did not run owes NOTHING.** Do not invent rows for modules you skipped — a
+   manifest padded to look complete is worse than a short one, because it makes the check pass while
+   describing work nobody did.
+3. **Phase 1 answers every row**: cite the id in a Phase-1 document, or reject it WITH A REASON in
+   the same line. Silence is neither, and it is the only outcome the check refuses to interpret
+   charitably.
+
+Deterministic half: `node .claude/hooks/check-handoff-manifest.cjs .` — `0` every output answered ·
+`1` a defect is PROVEN and NAMED (an output nobody answered for, a rejection with no reason, an
+empty manifest) · `2` THE CHECK DID NOT RUN (no brief — Phase 0 never ran, `--from-docs` skips it —
+no manifest section, no Phase-1 documents, a malformed or duplicated id, or the honest «НЕ
+ВЫПОЛНЕНА» with a reason). Exit `2` never means "all clear".
+
 ## Anti-Hallucination Rules
 
 - Search first — never answer from memory for facts

package/templates/.claude/agents/replicate-coordinator.md

@@ -8,9 +8,19 @@ Activated automatically by the `/replicate` command. Do NOT invoke directly.
 
 ## Responsibilities
 
-1. **Phase Management** — ensure correct phase sequence (0 → 1 → 2 → 3 → 4)
+1. **Phase Management** — ensure correct phase sequence (0 → 0.5 → 1 → 2 → 3 → 4).
+   Phase 0 is OPTIONAL and is skipped entirely by the `--from-docs` / `--skip-discovery` entry;
+   **Phase 0.5 (Source Product Profile) is MANDATORY and runs in every case**, which is why it is a
+   separate phase rather than a module inside Phase 0.
 2. **Context Passing** — carry forward outputs between phases:
    - Phase 0 → Phase 1: Product Discovery Brief
+   - Phase 0.5 → Phase 1: Source Product Profile (`docs/source-product-profile.md`) — a capture
+     status PER AXIS (`облик` and `путь` each answer `СНЯТ` / `НЕ ИЗМЕРЕНО` + reason /
+     `ИСТОЧНИКА НЕТ`, because they fail apart) plus the `FR-LOOK-nnn` seed rows of ONE family. A
+     `СНЯТ` profile's palette SUPERSEDES the industry palette of `025-cjm-prototype.md`; in the
+     other two states that table is a LABELLED fallback. The `путь` axis is captured by
+     `.claude/hooks/capture-source-path.cjs` (browser click-through; Playwright is an external
+     prerequisite, and its absence is the outcome `no-browser`, never a stalled run)
    - Phase 1 → Phase 2: 11 SPARC documents
    - Phase 2 → Phase 3: Validated docs + test-scenarios
    - Phase 3 → Phase 4: Complete toolkit

package/templates/.claude/commands/feature.md

@@ -70,11 +70,46 @@ implementation diffs.
 Read: `.claude/skills/sparc-prd-mini/SKILL.md`
 
 Generate per-feature SPARC docs in `docs/features/<feature>/`:
-- `01_specification.md` — requirements + acceptance criteria
-- `02_pseudocode.md` — algorithms + data flow
-- `03_architecture.md` — component placement + dependencies
-- `04_refinement.md` — edge cases + error paths
-- `05_completion.md` — testing + deployment notes
+
+### Phase 1 document role map
+
+`/feature` owns these per-feature filenames. Pass the complete map to `sparc-prd-mini`; the skill
+addresses the documents by role and must not redeclare these names.
+
+```yaml
+TARGET_CATALOG: docs/features/<feature>/
+DOCUMENT_ROLE_MAP:
+  specification: 01_specification.md
+  pseudocode: 02_pseudocode.md
+  architecture: 03_architecture.md
+  refinement: 04_refinement.md
+  completion: 05_completion.md
+```
+
+- `specification` — requirements + acceptance criteria
+- `pseudocode` — algorithms + data flow
+- `architecture` — component placement + dependencies
+- `refinement` — edge cases + error paths
+- `completion` — testing + deployment notes
+
+#### Blocking machine-key traceability gate
+
+After all five role targets are written, but before emitting the Phase 1 checkpoint or starting
+Phase 2, run the installed package utility from the project root:
+
+```bash
+CHECK_PIPELINE_GAPS="$(node -p "require.resolve('@dzhechkov/p-replicator/scripts/check-pipeline-gaps.sh')")" || {
+  printf 'NOT-ESTABLISHED packaged checker could not be resolved\n' >&2
+  exit 2
+}
+bash "$CHECK_PIPELINE_GAPS" "${CLAUDE_PROJECT_DIR:-.}" --traceability
+```
+
+Preserve its status and diagnostic verbatim. Exit `0` is the only advancing result. Exit `1` means
+named `specification->pseudocode` or `pseudocode->specification` gaps and returns to Phase 1 for
+repair. Exit `2` means the role map or document evidence is not established and stops the pipeline
+until that input is repaired. This rule is identical in MANUAL and AUTO modes; never turn either
+non-zero status into a warning.
 
 **Checkpoint:**
 ```
@@ -102,10 +137,46 @@ Output: `docs/features/<feature>/validation-report.md`
 
 1. Read SPARC docs from Phase 1
 2. Identify independent work units
-3. Spawn parallel `Task` tool calls, one per unit
-4. Each Task: implement + write tests + commit
-5. Coordinator merges/integrates after Tasks complete
-6. Run full test suite
+3. Establish the positive file receipt contract below
+4. Spawn parallel `Task` tool calls, one per unit
+5. Each Task: implement + write tests + commit + deliver its trace
+6. Coordinator validates every trace before merge/integration
+7. Run full test suite
+
+#### Canon before dispatch (required)
+
+**The canon MUST be frozen BEFORE dispatch.** Parallel units are N writers deriving names and
+numbers from one source; the collision exists ONLY IN THE UNION, so no worker can see it and no
+receipt can catch it. The coordinator records `docs/dispatch-plan.md` — the canon path and its
+sha256 — or runs the units sequentially.
+
+The same plan MUST assign OWNERSHIP: exactly one writer per file, the coordinator included, and a
+file born by SPLITTING another gets its owner AT CREATION — ownership never travels by itself.
+
+Every EDIT and every VERDICT MUST declare the sha256 of the source it was built on; a
+mismatch with the live file is a refusal WITHOUT mutation — a read copy is a snapshot of the moment
+of reading, not of the file.
+
+Field forms and closed value lists are in the checkers' headers:
+
+```bash
+node .claude/hooks/check-canon.cjs .
+node .claude/hooks/check-file-ownership.cjs .
+node .claude/hooks/check-source-version.cjs .
+```
+
+`0` frozen and intact · `1` a defect is PROVEN and named · `2` **THE CHECK DID NOT RUN**, which is
+never "all clear".
+
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every independent unit, a unique `WORK_UNIT_ID`.
+Resolve `TRACE_PATH` to an absolute path unique to `(RUN_ID, WORK_UNIT_ID)` and pass both fields.
+Require the worker to write a substantive body ending in `Status: completed` or `Status: failed` to
+`TRACE_PATH` before its one-line pointer. Before integration, MUST verify a regular, non-symlink,
+substantive, post-launch file with a terminal status. Narrative/chat/silence is never a receipt; any
+invalid receipt MUST block merge/completion. Full rule and bounded exception:
+`.claude/rules/swarm-file-evidence.md`.
 
 ### Phase 4: REVIEW (brutal-honesty-review)
 
@@ -123,6 +194,7 @@ Findings classified by severity. Critical (blocker | high) MUST be fixed.
 
 Skip per-phase user confirmations. Auto-decisions:
 - Phase 1: proceed if all docs exist
+- Phase 1 traceability: proceed only when `check-pipeline-gaps.sh` exits `0`; preserve exit `1`/`2`
 - Phase 2: proceed if 🟢 or 🟡; auto-retry once on 🔴
 - Phase 3: proceed if tests + lint + build green
 - Phase 4: auto-fix `high` if straightforward; halt on `blocker`

package/templates/.claude/commands/go.md

@@ -73,6 +73,15 @@ CHECK: feature_ent_available = fileExists(".claude/commands/feature-ent.md")
 Same as `/feature` but with idea2prd-manual + DDD coherence + ADR consistency
 + 7-agent validation + 6-agent review.
 
+### Delegated parallel-work receipt (required)
+
+For parallel work, assign each unit a unique `WORK_UNIT_ID` and unique absolute `TRACE_PATH`. The worker
+MUST write a substantive body ending in `Status: completed` or `Status: failed` to `TRACE_PATH` before
+its one-line pointer. Before merge/synthesis/completion, the selected pipeline MUST verify a regular,
+non-symlink, substantive, post-launch file with a terminal status. Narrative/chat/silence is never a
+receipt; any invalid receipt MUST block merge/completion, and this router never substitutes its report.
+Full rule: `.claude/rules/swarm-file-evidence.md`.
+
 ## Step 6: Post-Implementation
 
 1. Update roadmap: feature `status: done`, `files: [actually-touched]`

package/templates/.claude/commands/harvest.md

@@ -39,9 +39,9 @@ Read the skill: `.claude/skills/knowledge-extractor/SKILL.md`
 
 1. Determine mode from $ARGUMENTS (default: quick)
 2. Read skill: `.claude/skills/knowledge-extractor/SKILL.md`
-3. If mode == marker: create/append TOOLKIT_HARVEST.md, done
-4. If mode == quick: run all 4 phases without checkpoints
-5. If mode == full: run with checkpoints after each phase
+3. If mode == marker: create/append TOOLKIT_HARVEST.md; marker does not invoke `write-insight.cjs`; done
+4. If mode == quick: run all 4 phases without checkpoints, then run the required insight gate
+5. If mode == full: run with checkpoints after each phase, then run the required insight gate
 
 ### Phase Summary
 
@@ -50,8 +50,42 @@ Phase 1: AGENT REVIEW — scan codebase with 5 parallel agents
 Phase 2: CLASSIFY — categorize into 7 artifact types, filter exclusions
 Phase 3: DECONTEXTUALIZE — generalize, document, version
 Phase 4: INTEGRATE — write to toolkit, update index, harvest report
+Gate 5: PERSIST INSIGHT — quick/full must receive a valid writer receipt before completion
 ```
 
+### Phase 1 positive file receipts (required)
+
+Assign each perspective a unique `WORK_UNIT_ID` and unique absolute `TRACE_PATH`. Its agent MUST write
+a substantive body ending in `Status: completed` or `Status: failed` to `TRACE_PATH` before its one-line
+pointer. Before classification/synthesis, verify a regular, non-symlink, substantive, post-launch file
+with a terminal status. Narrative/chat/silence is never a receipt; any invalid receipt MUST block
+harvest completion. Full rule: `.claude/rules/swarm-file-evidence.md`.
+
+## REQUIRED INSIGHT PERSISTENCE GATE (quick/full only)
+
+After Phase 4 and before the normal harvest completion report:
+
+1. Select one specific, reusable finding from this run. Populate all fields in this JSON object:
+   `date` (`YYYY-MM-DD`, owned by this caller), `title`, `tags` (array), `problem`, `solution`, and
+   `references` (array). Do not invent a generic record merely to satisfy the gate.
+2. If the run produced no candidate, write nothing and report exactly that insight capture remains
+   incomplete because no candidate was found. This is distinct from silently skipping the gate.
+3. Otherwise, write the JSON to a temporary UTF-8 file outside `.claude/insights/`, then pass its
+   bytes on stdin to the project-root helper `.claude/hooks/write-insight.cjs`. Do not put record
+   contents in shell arguments. The helper owns lazy carrier creation, append preservation, and
+   exact-repeat suppression. It establishes the Markdown source of truth first, then attempts a
+   best-effort idempotent `dz teach` duplicate.
+4. Require exit zero and parse exactly one JSON receipt. Only `created`, `appended`, or `duplicate`
+   is valid. Verify `.claude/insights/index.md` exists after `created` or `appended`. The nested
+   `teach.state` is optional-projection observability, not a second persistence receipt.
+5. Delete the temporary JSON only after a valid receipt. Include its status and `entryCount` in the
+   completion report, plus `teach.state` when present. A failed teach retains Markdown and does not
+   block completion. If the writer exits non-zero or its receipt is absent/malformed, MUST NOT report
+   the harvest as completed; show the persistence failure and keep the input for diagnosis.
+
+`marker` mode is only a future-work marker: it does not invoke `write-insight.cjs`, does not create
+`.claude/insights/`, and does not claim a completed quick/full harvest.
+
 ### Module References
 
 | Phase | Module |
@@ -97,6 +131,7 @@ Phase 4: INTEGRATE — write to toolkit, update index, harvest report
 - Decontextualize in Phase 3 (no project-specific references)
 - Assign maturity level to every artifact
 - Record provenance (source project, date)
+- For quick/full with a real finding, persist one insight and validate the writer receipt before completion
 
 ### NEVER
 - Don't copy code verbatim — always decontextualize
@@ -104,3 +139,4 @@ Phase 4: INTEGRATE — write to toolkit, update index, harvest report
 - Don't extract library workarounds without expiry dates
 - Don't skip Phase 3 — undecontextualized artifacts are tech debt
 - Don't set maturity higher than 🔴 Alpha for first extraction
+- Don't report quick/full completion after a failed or unestablished insight write

package/templates/.claude/commands/myinsights.md

@@ -1,5 +1,5 @@
 ---
-description: Capture and recall development insights. Append a new insight to `.claude/insights/index.md` with structured fields (problem, solution, tags). The three most recent are injected into context at SessionStart.
+description: Capture and recall development insights. Markdown remains the source of truth; UserPromptSubmit uses armed dz recall with a local last-three fallback.
 argument-hint: '[recall <query> | <free-form insight>]'
 ---
 
@@ -10,22 +10,19 @@ argument-hint: '[recall <query> | <free-form insight>]'
 Build a project-local knowledge base of "грабли" (rakes) — errors, workarounds,
 discoveries — so they don't have to be re-learned.
 
-**What actually happens, stated exactly.** The `SessionStart` hook
-(`.claude/hooks/session-insights.cjs`, wired in `.claude/settings.json`) reads
-`.claude/insights/index.md` and injects the **three most recent entries**, by their
-order in the file. It prints them under the heading *"Recent project insights"* —
-which is what they are.
+**What actually happens, stated exactly.** `.claude/insights/index.md` is the Markdown
+source of truth. Capture establishes it first, then the writer makes a best-effort,
+idempotent `dz teach` duplicate. Missing or failed dz never changes the Markdown receipt.
 
-**There is no tag matching, and it is not an omission.** The hook fires at
-`SessionStart`, BEFORE you have said anything, so there is no current task to match
-tags against. Tags remain useful for a human reading or grepping the file, and for
-`/myinsights recall <query>`, which searches on demand — when a query exists.
+On `UserPromptSubmit`, `.claude/hooks/session-insights.cjs` queries with the actual prompt.
+Only a successful, non-empty `dz recall` result from the insight domain suppresses local
+delivery. Absent, failing, or empty recall falls back to the three most recent Markdown
+entries; a present-but-failing recall is named, while ordinary absence and empty output are
+quiet. `SessionStart` only keeps the missing-carrier hint.
 
-**The consequence, so nobody is surprised by it.** The file is append-only and the
-hook takes the LAST three. As a project accumulates entries — `insights-capture.md`
-plans for 50+ — earlier ones stop being injected. Selection by relevance would need
-to happen at a moment when a task is known; that is a separate design question, and
-it is filed rather than quietly implied here.
+**Fallback consequence.** The Markdown file is append-only, and local fallback takes the
+last three entries by file order. In that fallback, earlier ones stop being injected as the
+project grows. The dz path can rank older entries without replacing the durable carrier.
 
 ## Modes
 
@@ -68,22 +65,20 @@ Process:
 
 ## Storage
 
-`.claude/insights/index.md` — chronological log, Markdown format. One file per
-project to keep recall trivial.
+`.claude/insights/index.md` — chronological Markdown source of truth. The optional
+best-effort dz projection is derived from it and can be rebuilt by replay.
 
-## Auto-injection on SessionStart
+## Prompt-time injection on UserPromptSubmit
 
 The default `.claude/settings.json` configures `node .claude/hooks/session-insights.cjs`
-which: (1) reads recent insights, (2) prints them to stdout, (3) Claude Code
-captures stdout and injects into the initial context.
-
-This is what makes insights compounding: every session benefits from past
-mistakes without manual recall.
+for `UserPromptSubmit`. It emits one hook envelope from either armed dz recall or local
+fallback, never both. The same script remains on `SessionStart` only to reveal a missing
+Markdown carrier before the first capture.
 
 ## Related
 
 - `.claude/rules/insights-capture.md` — when/how to capture
 - `.claude/hooks/session-insights.cjs` — session injection
-- `/harvest` — extracts reusable knowledge at project end. **Honest limit:** it does
-  NOT read `.claude/insights/index.md` today (`grep -ci insight` over `harvest.md`
-  returns 0). The capture→harvest link is a stated intention, not a wired path.
+- `/harvest` — quick/full runs and `/myinsights` share the same Markdown carrier at
+  `.claude/insights/index.md`. Harvest capture is a required final persistence gate when the run
+  produced a reusable finding; manual capture remains available at any time. Both stay append-only.