@dzhechkov/p-replicator 1.10.4 → 1.12.0

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,22 @@ 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
+
+#### 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 returning a one-line pointer. Before integration, verify each path is a regular
+non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or silence is not a
+receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID, or probe-error units
+and refuse merge/completion unless every required receipt is valid and completed. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
 
 ### Phase 4: REVIEW (brutal-honesty-review)
 
@@ -123,6 +170,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,17 @@ 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 any selected pipeline that dispatches parallel work, allocate one `RUN_ID`, a unique
+`WORK_UNIT_ID`, and an absolute `TRACE_PATH` per unit. Require each worker to write a substantive body
+ending in `Status: completed` or `Status: failed` to `TRACE_PATH` before its one-line pointer. Before
+the routed pipeline reports merge, synthesis, or completion, verify each path is a regular non-symlink
+file, non-whitespace, post-launch, and terminal. Narrative output or silence is not a receipt. Name
+missing, stale, partial, unreadable, duplicate, failed, dead-PID, or probe-error units and refuse
+aggregation/completion unless every required receipt is valid and completed. The selected pipeline
+owns the paths; this router never substitutes its own report. See `.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,44 @@ 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)
+
+Before the five-agent dispatch, allocate one `RUN_ID`, then assign every perspective a unique
+`WORK_UNIT_ID` and absolute `TRACE_PATH`. Require each agent to write a substantive body ending in
+`Status: completed` or `Status: failed` to `TRACE_PATH` before returning a one-line pointer. Before
+classification or synthesis, verify every path is a regular non-symlink file, non-whitespace,
+post-launch, and terminal. Narrative output or silence is not a receipt. Name missing, stale, partial,
+unreadable, duplicate, failed, dead-PID, or probe-error perspectives and refuse harvest completion
+unless every required receipt is valid and completed. See `.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 +133,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 +141,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.

package/templates/.claude/commands/replicate.md

@@ -329,6 +329,15 @@ Read the skill: `.claude/skills/requirements-validator/SKILL.md`
 The sixth lens is the only one that looks OUTSIDE the documents. The other five compare our own
 output with our own output, which cannot discover that a service does not do what we assumed.
 
+**Positive file receipt (required).** Before dispatch, allocate one `RUN_ID` and give every
+validation lens a unique `WORK_UNIT_ID` and absolute `TRACE_PATH`. Each validator must write a
+substantive report fragment ending in `Status: completed` or `Status: failed` to `TRACE_PATH` before
+its one-line pointer. Before AGGREGATE, verify every path is a regular non-symlink file,
+non-whitespace, post-launch, and terminal. Narrative output or silence is not a receipt. Name
+missing, stale, partial, unreadable, duplicate, failed, dead-PID, or probe-error lenses and refuse
+aggregation/completion unless every required receipt is valid and completed. See
+`.claude/rules/swarm-file-evidence.md`.
+
 **Process (iterative, max 3 iterations):**
 
 ```
@@ -475,7 +484,7 @@ Read the skill: `.claude/skills/cc-toolkit-generator-enhanced/SKILL.md`
 - **Pre-shipped by `npx p-replicator init` — do NOT overwrite or regenerate:**
   - All 10 skills in `.claude/skills/`
   - All 11 commands: `/replicate`, `/harvest`, `/start`, `/plan`, `/feature`, `/go`, `/run`, `/next`, `/myinsights`, `/docs`, `/deploy`
-  - All 6 rules: `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`, `docker-ports`
+  - All 9 rules: `cost-of-detection-ladder`, `replicate-pipeline`, `skill-interface-protocol`, `git-workflow`, `insights-capture`, `feature-lifecycle`, `docker-ports`, `swarm-file-evidence`, `honest-configuration`
   - All 4 pipeline agents: `replicate-coordinator`, `product-discoverer`, `doc-validator`, `harvest-coordinator`
   - `.claude/settings.json` + cross-platform Node hook scripts in `.claude/hooks/`
 - Phase 3 generates ONLY project-specific artifacts derived from SPARC docs (see below).

package/templates/.claude/commands/start.md

@@ -69,6 +69,14 @@ Generate: src/<files>, tests/<files>, package.json, README.md
 Commits: one per logical group.
 ```
 
+Before dispatch, allocate one `RUN_ID`, a unique `WORK_UNIT_ID`, and an absolute `TRACE_PATH` for
+each package. Require each Task to write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before its one-line pointer. Before Phase 3 integration, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is not a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID, or
+probe-error packages and refuse integration/completion unless every required receipt is valid and
+completed. See `.claude/rules/swarm-file-evidence.md`.
+
 ### Phase 3: Integration (sequential)
 
 1. Verify cross-package imports