@dzhechkov/p-replicator 1.12.0 → 1.13.2

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/03-generate-p0.md

@@ -39,7 +39,8 @@ From the Instrument Map this module uses:
 > gate in `.claude/rules/replicate-pipeline.md` ("What Gets Generated vs Pre-shipped").
 > For these items, **VERIFY they exist — do NOT regenerate or overwrite them:**
 > - Commands: `start.md` (Item 4), `myinsights.md` (Item 5), `feature.md` (Item 6)
-> - Rules: `git-workflow.md` (Item 7), `insights-capture.md` (Item 8), `feature-lifecycle.md` (Item 9)
+> - Rules: `git-workflow.md` (Item 7), `insights-capture.md` (Item 8), `feature-lifecycle.md` (Item 9),
+>   `swarm-file-evidence.md` (Item 9b)
 > - Config: `.claude/settings.json` + `.claude/hooks/` scripts (Item 10)
 >
 > Treat their "Generate `.claude/...`" instructions as "confirm present; enhance content
@@ -238,6 +239,11 @@ Key generation steps:
 **Critical rule:** /start MUST reference actual docs in `docs/`, never hallucinate
 code from memory. Every Phase 2 Task includes explicit doc references.
 
+**Second critical rule:** Phase 2 dispatches parallel Tasks, so the generated command MUST carry
+the "Positive file receipt (required)" block from the template. Every package Task gets its own
+`WORK_UNIT_ID` and absolute `TRACE_PATH`, and Phase 3 may not begin until
+`node .claude/hooks/check-swarm-receipts.cjs <manifest>` exits 0 (see Item 9b).
+
 **Output path:** `.claude/commands/start.md`
 
 ---
@@ -291,6 +297,8 @@ Phase 3: IMPLEMENT (swarm + parallel tasks)
   Read validated SPARC docs as source of truth
   Use @planner, @architect, implementation agents
   Modular design for reuse
+  Positive file receipt: one WORK_UNIT_ID + absolute TRACE_PATH per unit,
+    terminal Status: line last, verified before merge (see Item 9b)
   Commit per logical unit: feat(<feature-name>): <what>
 
 Phase 4: REVIEW (brutal-honesty-review, swarm)
@@ -365,6 +373,38 @@ Generate `.claude/rules/feature-lifecycle.md` with:
 
 **Output path:** `.claude/rules/feature-lifecycle.md`
 
+The generated rule MUST carry the "Positive file receipt (required)" block from Section 3 of the
+template verbatim. A lifecycle that dispatches parallel agents without it is INCOMPLETE, and
+`06-package-deliver.md` CHECK 7b fails delivery on it.
+
+---
+
+#### Item 9b: swarm-file-evidence.md rule
+
+**Template:** `view() references/templates/swarm-file-evidence.md` (Section 1)
+> CRITICAL: COPY the full template. Do NOT compress or summarize.
+
+Generate `.claude/rules/swarm-file-evidence.md` — the contract that makes a parallel unit's result
+a FILE rather than a reply.
+
+**Why this item exists, in one paragraph you should not skip:** a worker that died looks exactly
+like a worker that is still running, because both are silent. Silence therefore reads as "in
+progress", and a coordinator can report in good faith that a review is running when no review
+exists — the absence of a receipt is indistinguishable from unfinished work. Declaring the result
+to be a file at a named path collapses that ambiguity: no file, no work, and a machine can say so.
+
+- **Do NOT overwrite** an existing `.claude/rules/swarm-file-evidence.md` — a project created by
+  `npx @dzhechkov/p-replicator init` already has it, pre-shipped and protected by the
+  do-not-overwrite gate.
+- Generate it when the path is ABSENT, which is the case for every toolkit produced into a project
+  this package never initialised. That is the whole point of this item: the cure has to travel with
+  the generated toolkit, not only with the installer.
+- Also copy `templates/.claude/hooks/check-swarm-receipts.cjs` (or regenerate it from
+  Section 3 of the template) so the contract has its deterministic half — text alone is layer 2 and
+  fails silently.
+
+**Output path:** `.claude/rules/swarm-file-evidence.md` (+ `.claude/hooks/check-swarm-receipts.cjs`)
+
 ---
 
 #### Item 10: settings.json hooks
@@ -559,6 +599,8 @@ Generate items in this order to resolve dependencies:
 4. Item 7: git-workflow.md (rule, no deps)
 5. Item 8: insights-capture.md (rule, no deps)
 6. Item 9: feature-lifecycle.md (rule, references skills from step 1)
+6b. Item 9b: swarm-file-evidence.md (rule + check-swarm-receipts.cjs; every later item that
+    dispatches parallel agents references it, so it must exist before them)
 7. Item 4: /start command (references docs, rules, skills)
 8. Item 5: /myinsights command (references insights-capture rule)
 9. Item 6: /feature command (references lifecycle skills, rules)
@@ -587,6 +629,8 @@ P0 Mandatory Generated:
   [x] .claude/rules/git-workflow.md   0.8 KB
   [x] .claude/rules/insights-capture.md  1.9 KB
   [x] .claude/rules/feature-lifecycle.md 2.4 KB
+  [x] .claude/rules/swarm-file-evidence.md 2.6 KB
+  [x] .claude/hooks/check-swarm-receipts.cjs (0/1/2)
   [x] .claude/settings.json           1.2 KB
   [x] 6 lifecycle skills copied       (sparc-prd-mini, explore,
        goap-research, problem-solver-enhanced,
@@ -659,6 +703,7 @@ This module reads the following reference/template files during execution:
 | `view() references/templates/start-command.md` | /start command template with placeholder fill instructions | Item 4: /start |
 | `view() references/templates/feature-lifecycle.md` | Skill copying protocol (Sec 1), /feature command template (Sec 2), feature-lifecycle rule template (Sec 3), CLAUDE.md integration (Sec 4) | Items 6, 9, 11-16 |
 | `view() references/templates/insights-system.md` | /myinsights command template (Sec 1), insights-capture rule template (Sec 2), Stop hook template (Sec 3), CLAUDE.md integration (Sec 4) | Items 5, 8, 10 |
+| `view() references/templates/swarm-file-evidence.md` | swarm-file-evidence rule body (Sec 1), the positive file receipt seam to paste into every dispatch site (Sec 2), the `check-swarm-receipts.cjs` 0/1/2 checker + manifest shape (Sec 3), placement map (Sec 4) | Items 4, 6, 9, 9b |
 
 These files are part of the cc-toolkit-generator-enhanced skill at:
 `.claude/skills/cc-toolkit-generator-enhanced/references/`

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/04-generate-p1.md

@@ -245,13 +245,15 @@ IF has_ddd:
       - Phase 2: VALIDATE (requirements-validator swarm, 7 agents, score >= 70)
       - Phase 3: IMPLEMENT (parallel agents per Bounded Context)
       - Phase 4: REVIEW (brutal-honesty-review swarm, 6 agents)
+      - Positive file receipt block VERBATIM in Phase 3 (P0 Item 9b installs the rule it cites)
       - Output to docs/features/<feature-name>/ with full subdirectory structure
 
   6b. Generate .claude/rules/feature-lifecycle-ent.md
       - When to use /feature-ent vs /feature decision matrix
       - Enterprise planning rules (full idea2prd-manual, mandatory DDD)
       - Enterprise validation rules (7 agents, extended scope)
-      - Enterprise implementation rules (Task per Bounded Context)
+      - Enterprise implementation rules (Task per Bounded Context, each with its own
+        WORK_UNIT_ID and absolute TRACE_PATH — the positive file receipt block VERBATIM)
       - Enterprise review rules (6 agents, ADR + fitness verification)
 
   6c. Copy skill directories with path rewrite:
@@ -468,6 +470,10 @@ All of the following must pass before proceeding to Phase 5:
 
 - [ ] `/feature-ent` command includes all 4 phases with checkpoints
 - [ ] `feature-lifecycle-ent.md` rule includes decision matrix (/feature vs /feature-ent)
+- [ ] `/feature-ent` Phase 3 and `feature-lifecycle-ent.md` Implementation each carry the positive
+      file receipt block (`WORK_UNIT_ID`, absolute `TRACE_PATH`, terminal `Status:` line, refusal to
+      merge without it) and cite `.claude/rules/swarm-file-evidence.md`. A Bounded-Context agent
+      that died is silent exactly like one still working, so only the file separates them
 - [ ] `idea2prd-manual/` skill copied with ALL path rewrites applied (3 external skill paths)
 - [ ] `goap-research-ed25519/` skill copied completely
 - [ ] No duplicate skill copies (explore, problem-solver-enhanced already in P0)

package/templates/.claude/skills/cc-toolkit-generator-enhanced/modules/06-package-deliver.md

@@ -61,7 +61,8 @@ CHECK 3: /start command
   - File exists at .claude/commands/start.md
   - Contains complete project generation instructions
   - Includes all packages from IPM
-  - Uses Task tool for parallelism where appropriate
+  - Uses Task tool for parallelism where appropriate, under the positive file receipt contract
+    (see CHECK 7b — a parallel Task without a TRACE_PATH is a delivery failure)
   - Includes Docker health check verification
   - References actual SPARC/idea2prd docs (not hallucinated paths)
   - IF has_database: includes DB migration + seed steps
@@ -87,6 +88,23 @@ CHECK 7: feature-lifecycle.md rule
   - Documents the 4-phase lifecycle protocol
   - Includes phase skip guidance
 
+CHECK 7b: the swarm file-evidence contract reached the toolkit  [FAIL-CLOSED]
+  - File exists at .claude/rules/swarm-file-evidence.md
+  - File exists at .claude/hooks/check-swarm-receipts.cjs
+  - EVERY generated artifact that dispatches parallel agents names WORK_UNIT_ID and an absolute
+    TRACE_PATH and refuses merge without a terminal receipt. At minimum:
+    [ ] .claude/commands/feature.md          (Phase 3, and Phase 2/4 by reference)
+    [ ] .claude/rules/feature-lifecycle.md   (Implementation)
+    [ ] .claude/commands/start.md            (Phase 2 package Tasks)
+    [ ] .claude/commands/feature-ent.md      IF DDD
+    [ ] .claude/rules/feature-lifecycle-ent.md IF DDD
+    [ ] .claude/commands/go.md, run.md       IF automation commands generated
+  - The check is TEXTUAL and mechanical: grep each file for `TRACE_PATH`. A file that dispatches
+    agents and does not name it FAILS delivery — there is no "the coordinator will remember".
+  - Why fail-closed: a worker that died is silent and a worker that is running is silent, so a
+    toolkit without this contract cannot tell the two apart and will report progress on work that
+    stopped. Shipping that is shipping a defect, not an omission.
+
 CHECK 8: 6 lifecycle skills
   - All 6 skills copied to .claude/skills/:
     [ ] sparc-prd-mini/SKILL.md
@@ -433,6 +451,7 @@ Compile the complete file tree of everything produced, annotated with phase and
 |       |-- git-workflow.md                <- P0 [size] [PASS/FAIL]
 |       |-- insights-capture.md            <- P0 [size] [PASS/FAIL]
 |       |-- feature-lifecycle.md           <- P0 [size] [PASS/FAIL]
+|       |-- swarm-file-evidence.md         <- P0 [size] [PASS/FAIL]
 |       |-- feature-lifecycle-ent.md       <- P1 IF DDD [size] [PASS/FAIL]
 |       |-- secrets-management.md          <- P0 IF external APIs [size] [PASS/FAIL]
 |       |-- domain-model.md                <- P0 IF DDD [size] [PASS/FAIL]
@@ -515,7 +534,6 @@ IF any P0 mandatory check fails:
 
   FAILED CHECKS:
     - [Check N]: [description of what failed and where]
-    - [Check N]: [description of what failed and where]
 
   Auto-fix attempted: [Y/N]
   Remaining failures after auto-fix: [count]

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/claude-md-strategy.md

@@ -73,6 +73,13 @@ These are identical regardless of pipeline.
 - Use `Task` tool for independent subtasks
 - Run tests, linting, type-checking in parallel
 - For complex features: spawn specialized agents
+- **Every parallel unit delivers a FILE, not a reply.** Give each one a unique `WORK_UNIT_ID` and an
+  absolute `TRACE_PATH`; it writes a substantive body ending in `Status: completed` or
+  `Status: failed` there before its one-line pointer. A dead worker and a working worker are both
+  silent, so silence is never progress. Verify before merging with
+  `node .claude/hooks/check-swarm-receipts.cjs <manifest>` (0 = all completed, 1 = a unit is
+  undelivered or failed, 2 = the check did not run). Full contract:
+  `.claude/rules/swarm-file-evidence.md`.
 
 ## Swarm Agents
 | Scenario | Agents | Parallelism |

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/automation-commands.md

@@ -165,6 +165,23 @@ Then evaluate the feature to determine the right pipeline:
 - Run tests in parallel with implementation of unrelated components
 - Never parallelize tasks that have data dependencies
 
+### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
+
+This matters most in an AUTONOMOUS loop, where nobody is watching: a worker that died is silent and
+a worker that is running is silent, so the loop keeps reporting progress on work that stopped hours
+ago. The file receipt is what turns that into a red exit code instead of a comfortable narrative.
+
 ## Git Strategy
 
 - Commit after each logical unit of work (not giant commits)

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/feature-lifecycle-ent.md

@@ -149,8 +149,8 @@ Use swarm of agents to validate:
 | validator-coherence | All docs cross-ref | PRD↔DDD↔ADR↔C4 consistency |
 
 **Iterative loop (max 3 iterations):**
-1. Run all validators in parallel (Task tool)
-2. Aggregate gaps and blocked items
+1. Run all validators in parallel (Task tool), under the positive file receipt contract below
+2. Aggregate gaps and blocked items — only from validators whose receipt is terminal-completed
 3. Fix gaps in documents
 4. Re-validate
 5. Repeat until: no BLOCKED items, average score ≥70
@@ -175,9 +175,24 @@ When documentation is ready for implementation:
 4. Generate tests from Gherkin .feature files
 5. Validate Fitness Functions during implementation
 6. Save frequent commits to GitHub
+7. Validate every trace before merge or integration
+
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
 
 **Implementation rules:**
-- Each Bounded Context gets its own Task for parallel execution
+- Each Bounded Context gets its own Task for parallel execution, with its own `WORK_UNIT_ID` and
+  `TRACE_PATH`
 - Reference docs (pseudocode, DDD tactical, ADR), don't hallucinate code
 - Commit after each logical unit: `feat(<feature-name>): <what>`
 - Run tests from .feature files in parallel with implementation
@@ -207,8 +222,9 @@ Use swarm of agents for review:
 Process:
 1. Run brutal-honesty-review on implementation
 2. Verify ADR compliance — each decision reflected in code
-3. Verify Fitness Functions pass
-4. Fix identified issues (use Task tool for parallel fixes)
+3. Verify Fitness Functions pass — every review agent delivers under the same positive file
+   receipt contract as Phase 3; a reviewer that returned nothing did not review
+4. Fix identified issues (use Task tool for parallel fixes, same contract)
 5. Save frequent commits: `fix(<feature-name>): <what>`
 6. Benchmark performance after implementation
 7. Re-review critical findings until clean
@@ -302,6 +318,24 @@ Enterprise features with complex domains follow the 4-phase lifecycle:
 
 ### Implementation (Phase 3)
 - One parallel Task per Bounded Context
+
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
+
+Why the file and not the reply: a worker that died looks exactly like a worker still running —
+both are silent — so a coordinator can report in good faith that a Bounded Context is under way
+when nothing is running. A named file turns that into a fact a machine can check.
+
 - Read pseudocode .pseudo files — don't hallucinate code
 - Enforce aggregate invariants from DDD tactical docs
 - Generate test stubs from Gherkin .feature files
@@ -388,6 +422,10 @@ Complex domain features use the enterprise lifecycle: `/feature-ent [name]`
 3. **IMPLEMENT** — parallel agents per Bounded Context from validated docs
 4. **REVIEW** — brutal-honesty-review swarm (6 agents) → ADR + fitness verified
 
+Every swarm phase delivers under `.claude/rules/swarm-file-evidence.md`: each parallel unit writes
+a file at a named `TRACE_PATH`, and an agent's reply is a pointer, never the result. Verify with
+`node .claude/hooks/check-swarm-receipts.cjs <manifest>` before merging anything.
+
 Use `/feature` for simple features, `/feature-ent` for complex domain features.
 
 Available enterprise lifecycle skills in `.claude/skills/`:

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/feature-lifecycle.md

@@ -133,8 +133,8 @@ Use swarm of agents to validate:
 | validator-coherence | All SPARC files | Cross-reference consistency |
 
 **Iterative loop (max 3 iterations):**
-1. Run all validators in parallel (Task tool)
-2. Aggregate gaps and blocked items
+1. Run all validators in parallel (Task tool), under the positive file receipt contract below
+2. Aggregate gaps and blocked items — only from validators whose receipt is terminal-completed
 3. Fix gaps in SPARC documents
 4. Re-validate
 5. Repeat until: no BLOCKED items, average score ≥70
@@ -156,10 +156,24 @@ When SPARC plan is ready for implementation:
    - Implementation agents — parallel Task tool for independent modules
 3. **Make implementation modular** for reuse in other cases and applications
 4. Save frequent commits to GitHub
-5. Spawn concurrent tasks to speed up development
+5. Spawn concurrent tasks to speed up development, under the contract below
+6. Validate every trace before merge or integration
+
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
 
 **Implementation rules:**
-- Each module gets its own Task for parallel execution
+- Each module gets its own Task for parallel execution, with its own `WORK_UNIT_ID` and `TRACE_PATH`
 - Reference SPARC docs, don't hallucinate code
 - Commit after each logical unit: `feat(<feature-name>): <what>`
 - Run tests in parallel with implementation
@@ -185,8 +199,9 @@ Use swarm of agents for review:
 | testing | Test coverage | Edge cases, missing tests |
 
 Process:
-1. Run brutal-honesty-review on implementation
-2. Fix identified issues (use Task tool for parallel fixes)
+1. Run brutal-honesty-review on implementation — every review agent delivers under the same
+   positive file receipt contract as Phase 3; a reviewer that returned nothing did not review
+2. Fix identified issues (use Task tool for parallel fixes, same contract)
 3. Save frequent commits: `fix(<feature-name>): <what>`
 4. Benchmark after implementation
 5. Re-review critical findings until clean
@@ -265,8 +280,25 @@ Every new feature MUST follow the 4-phase lifecycle:
 - Run tests in parallel with development
 - Format: `feat(<feature-name>): <description>`
 
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
+
+Why the file and not the reply: a worker that died looks exactly like a worker still running —
+both are silent — so a coordinator can report in good faith that work is under way when none is.
+A named file turns that into a fact a machine can check.
+
 ### Review (Phase 4)
-- Use brutal-honesty-review with swarm of agents
+- Use brutal-honesty-review with swarm of agents, under the same positive file receipt contract
 - No sugar-coating — find real problems
 - Fix all critical and major issues before marking complete
 - Benchmark performance after implementation
@@ -323,6 +355,10 @@ New features use the 4-phase lifecycle: `/feature [name]`
 3. **IMPLEMENT** — parallel agents from validated docs
 4. **REVIEW** — brutal-honesty-review swarm → fix all criticals
 
+Every swarm phase delivers under `.claude/rules/swarm-file-evidence.md`: each parallel unit writes
+a file at a named `TRACE_PATH`, and an agent's reply is a pointer, never the result. Verify with
+`node .claude/hooks/check-swarm-receipts.cjs <manifest>` before merging anything.
+
 Available lifecycle skills in `.claude/skills/`:
 - `sparc-prd-mini` (orchestrator, delegates to explore, goap-research, problem-solver-enhanced)
 - `explore` (Socratic questioning → Product Brief)

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/start-command.md

@@ -54,8 +54,25 @@ Generate:
 {{PACKAGE_FILE_LIST}}
 
 **Commits:** {{PACKAGE_COMMITS}}
+**Receipt:** write the substantive summary to `TRACE_PATH`, terminal line last, then reply one line.
 {{/FOR_EACH_PACKAGE}}
 
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. Run `node .claude/hooks/check-swarm-receipts.cjs <manifest>` — exit 0 all
+completed, exit 1 undelivered or failed, exit 2 the check did not run. See
+`.claude/rules/swarm-file-evidence.md` for mechanics and the bounded non-atomic-write exception.
+
+Phase 3 may not begin until that check exits 0. A package Task that produced no trace produced no
+package, however confidently it reported.
+
 ### Phase 3: Integration (sequential)
 
 1. **Verify cross-package imports** (shared modules used correctly)
@@ -177,7 +194,8 @@ Check Architecture.md for database presence:
 ### Key Principles
 
 1. **Docs as source of truth** — every Task must reference specific docs, never generate from memory
-2. **Maximize parallelism** — independent packages run as parallel Tasks
+2. **Maximize parallelism** — independent packages run as parallel Tasks, each delivering its own
+   file receipt; a Task's reply is a pointer, never the result
 3. **Atomic commits** — one commit per logical change, not one giant commit
 4. **Full integration** — Phase 3 MUST include Docker build + start + health check (+ DB if applicable)
 5. **Error recovery** — git commits after each phase ensure progress is saved

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/swarm-file-evidence.md

@@ -0,0 +1,151 @@
+# Swarm File Evidence Templates
+
+> The swarm contract, in the form the GENERATOR emits it. Everything below is written INTO the
+> target project — it is not guidance for this skill.
+>
+> WHY THIS FILE EXISTS. A worker that died looks exactly like a worker that is still running: both
+> are silent. Silence therefore reads as `in progress`, and a coordinator reports in good faith
+> that the review is running when no review exists. The absence of a receipt is indistinguishable
+> from unfinished work, and so it reads as progress. The cure is to declare the RESULT of every
+> parallel unit to be a FILE at a named path: no file, no work — and that is a fact a machine can
+> establish, not a feeling a reader has to trust.
+>
+> MEASURED 2026-09-01 (the defect this closes): the generated feature lifecycle told the toolkit to
+> launch parallel agents 22 times and required a file result zero times, while the package that
+> emits it had already carried the cure in nine of its own files. The generator reproduced in every
+> consumer project a defect its author had already fixed at home.
+
+---
+
+## 1. Rule Template: `swarm-file-evidence.md`
+
+**Output path:** `.claude/rules/swarm-file-evidence.md`
+
+**Do NOT overwrite** an existing file at that path — `npx @dzhechkov/p-replicator init` pre-ships
+this rule, and a project initialised that way already has it. Generate it only when the path is
+absent, which is the case for every toolkit produced into a project this package never initialised.
+
+Emit the body below VERBATIM. It is byte-identical to the pre-shipped rule, and
+`tests/unit/generator-swarm-contract.test.js` asserts that identity, so the two cannot drift.
+
+```markdown
+# Swarm File Evidence
+
+## Rule
+
+Every parallel work unit has a named file result. A narrative reply is only a pointer; silence is
+neither progress nor completion. The coordinator may aggregate only positive, attributable terminal
+receipts from the assigned files.
+
+## Mechanics
+
+1. Before dispatch, allocate a run-unique `RUN_ID` and a unique `WORK_UNIT_ID`. Resolve one absolute
+   `TRACE_PATH` per `(RUN_ID, WORK_UNIT_ID)`, record its pre-launch state, and pass both fields to the
+   worker. Two workers never share a path.
+2. The worker writes a substantive Markdown body to a temporary regular file in the same directory,
+   appends exactly `Status: completed` or `Status: failed` as the final line, renames it to
+   `TRACE_PATH`, then returns a one-line pointer. The terminal marker is written last.
+3. Before merge, synthesis, or completion, the coordinator checks each assigned path: absolute and
+   unique; regular and non-symlink; readable and non-whitespace; absent before launch or observably
+   changed after launch; final line terminal. It reads the file as the payload and reports
+   `valid receipts / required receipts` with every failed `WORK_UNIT_ID` and path.
+4. `Status: completed` permits consumption. `Status: failed` is a delivered failure and blocks a
+   successful aggregate. Missing, empty, stale, partial, unreadable, duplicate, or probe-error
+   evidence is undelivered or inconclusive. A dead PID stops waiting as failure; a live PID may only
+   extend waiting. Neither PID state proves delivery.
+
+## Bounded exception
+
+If atomic rename is unavailable, write directly to `TRACE_PATH` and append the terminal marker last;
+until that line exists the file is partial. Host-authoritative liveness may extend a deadline, but it
+cannot replace the file result or turn missing evidence into success.
+
+## Observable violation → replacement
+
+| Observable violation | Required replacement |
+|---|---|
+| Task report exists but `TRACE_PATH` does not | Name the unit/path, mark undelivered, and refuse aggregation. |
+| File is empty, stale, symlinked, unreadable, or non-terminal | Keep the evidence out of the aggregate and rerun or diagnose that unit. |
+| Status says `running` but its recorded PID is dead | Close the unit as failed; do not report continued work from silence. |
+| Fewer than all required receipts are terminal-completed | Report the partial ratio and refuse completion. |
+
+## Self-check
+
+For every parallel unit, point to its assignment containing `WORK_UNIT_ID` and absolute `TRACE_PATH`,
+then point to the coordinator check performed before aggregation. Exercise missing, empty, stale,
+partial, failed, dead-PID, and probe-error traces; only a fresh substantive file ending in
+`Status: completed` may satisfy delivery.
+```
+
+---
+
+## 2. Seam Template: the positive file receipt
+
+**Paste this block VERBATIM into every generated instruction that dispatches parallel agents** —
+the `/feature` and `/feature-ent` commands, the `feature-lifecycle` rules, `/start` Phase 2, the
+autonomous `/run` and `/go` loops, and any pipeline a project builds with `pipeline-forge`.
+It is short on purpose: a contract nobody can afford to repeat is a contract that gets dropped.
+
+```markdown
+#### Positive file receipt (required)
+
+Before dispatch, allocate one `RUN_ID` and, for every unit, a unique `WORK_UNIT_ID` plus an
+absolute `TRACE_PATH` unique to `(RUN_ID, WORK_UNIT_ID)`; record the launch instant and pass both
+fields to the worker. Each worker must write a substantive body ending in `Status: completed` or
+`Status: failed` to `TRACE_PATH` before it returns its one-line pointer. Before merge, verify every
+path is a regular non-symlink file, non-whitespace, post-launch, and terminal. Narrative output or
+silence is never a receipt. Name missing, stale, partial, unreadable, duplicate, failed, dead-PID,
+or probe-error units and refuse merge, aggregation, or completion until every required receipt is
+valid and completed. See `.claude/rules/swarm-file-evidence.md` for mechanics and the bounded
+non-atomic-write exception.
+```
+
+## 3. The deterministic half: `check-swarm-receipts.cjs`
+
+Section 2 is layer-2 text — it is read every run and violated in silence. The layer-1 half is a
+utility that answers the same question without a model in the loop:
+
+```bash
+node .claude/hooks/check-swarm-receipts.cjs .claude/traces/<RUN_ID>/receipts.json
+```
+
+Three exit codes, and the third is the point:
+
+| Exit | Meaning | Coordinator's obligation |
+|------|---------|--------------------------|
+| `0` | every receipt is fresh, substantive and `Status: completed` | may aggregate |
+| `1` | at least one unit is undelivered or delivered `Status: failed` | refuse merge; name the units |
+| `2` | THE CHECK DID NOT RUN — no manifest, malformed assignment, unreadable trace, or a still-live worker | refuse merge; this is an unknown, never a pass |
+
+The coordinator writes the manifest BEFORE dispatch, which is what makes freshness checkable at all
+— `launchMs` cannot be recovered afterwards:
+
+```json
+{
+  "runId": "feature-auth-2026-09-01T12-00-00Z",
+  "launchMs": 1756728000000,
+  "units": [
+    { "workUnitId": "api",  "tracePath": "/abs/project/.claude/traces/<RUN_ID>/api.md",  "pid": 12345 },
+    { "workUnitId": "docs", "tracePath": "/abs/project/.claude/traces/<RUN_ID>/docs.md" }
+  ]
+}
+```
+
+`pid` is optional and can only move an ABSENT trace between "undelivered" and "still waiting". A
+live worker may extend waiting; liveness has never been delivery.
+
+## 4. Where the generator must place all of this
+
+| Generated artifact | What must appear |
+|---|---|
+| `.claude/rules/swarm-file-evidence.md` | Section 1 verbatim, unless the path already exists |
+| `.claude/commands/feature.md` — Phase 3 | Section 2 block |
+| `.claude/rules/feature-lifecycle.md` — Implementation | Section 2 block |
+| `.claude/commands/feature-ent.md` + `feature-lifecycle-ent.md` | Section 2 block |
+| `.claude/commands/start.md` — Phase 2 | Section 2 block |
+| Autonomous loop commands (`/run`, `/go`) | Section 2 block |
+| Any `pipeline-forge` pipeline with a swarm stage | Section 2 block |
+| `CLAUDE.md` lifecycle section | one line naming the rule, so the contract is discoverable |
+
+A generated toolkit that dispatches parallel agents anywhere and carries none of this is INCOMPLETE
+— `06-package-deliver.md` fails delivery on it.