@atlashub/smartstack-cli 4.17.1 → 4.19.0

package/templates/skills/{business-analyse → derive-prd}/references/prd-generation.md

@@ -1,258 +1,262 @@
-# PRD v3.0 Structure & Validation Rules
-
-Source: business-analyse step-05c-ralph-readiness.md
-
-## PRD File Format v3.0
-
-### File Location
-
-```
-.ralph/prd-{moduleCode}.json
-```
-
-Example: `.ralph/prd-Projects.json`, `.ralph/prd-TimeTracking.json`
-
----
-
-## Structure Requirements
-
-### 1. Version Field (MANDATORY)
-
-```json
-{
-  "$version": "3.0.0"
-}
-```
-
-**Validation:**
-- MUST be exactly `"3.0.0"`
-- BLOCKING if missing or wrong version
-
-**Common Error:**
-```
-BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
-Fix: Re-run ss derive-prd with latest version
-```
-
----
-
-### 2. Implementation Section (MANDATORY)
-
-**CRITICAL:** `filesToCreate` MUST be under `implementation`, NOT at root level.
-
-**Correct Structure:**
-```json
-{
-  "$version": "3.0.0",
-  "implementation": {
-    "filesToCreate": {
-      "domain": [...],
-      "application": [...],
-      "infrastructure": [...],
-      "api": [...],
-      "frontend": [...],
-      "seedData": [...],
-      "tests": [...]
-    }
-  }
-}
-```
-
-**Wrong Structure (v2.x legacy):**
-```json
-{
-  "$version": "3.0.0",
-  "filesToCreate": {  // ❌ WRONG - at root level
-    "domain": [...]
-  }
-}
-```
-
-**Validation:**
-- IF `prd.filesToCreate` exists at root level → BLOCKING ERROR
-- IF `prd.implementation.filesToCreate` missing → BLOCKING ERROR
-
-**Fix Command:**
-```bash
-ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json
-```
-
----
-
-### 3. Seven Categories (MANDATORY)
-
-All PRD files MUST include these 7 categories under `implementation.filesToCreate`:
-
-| Category | Description | Examples |
-|----------|-------------|----------|
-| **domain** | Domain entities, value objects, domain services | `Project.cs`, `ProjectStatus.cs` |
-| **application** | Application services, DTOs, interfaces | `ProjectService.cs`, `CreateProjectDto.cs` |
-| **infrastructure** | Data access, repositories, EF Core config | `ProjectRepository.cs`, `ProjectConfiguration.cs` |
-| **api** | Controllers, API endpoints | `ProjectsController.cs` |
-| **frontend** | React pages, components, hooks | `ProjectsPage.tsx`, `useProjects.ts` |
-| **seedData** | Seed data classes | `ProjectSeedData.cs` |
-| **tests** | Unit tests, integration tests | `ProjectServiceTests.cs`, `ProjectsControllerTests.cs` |
-
-**Validation:**
-```javascript
-const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
-const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);
-
-if (missingCategories.length > 0) {
-  BLOCKING_ERROR(`Missing categories: ${missingCategories.join(', ')}`);
-}
-```
-
-**Common Errors:**
-- Missing `tests` category → often forgotten
-- Missing `seedData` category → sometimes omitted for modules without seed data
-- Empty arrays allowed (e.g., `"seedData": []`) if genuinely no files needed
-
----
-
-### 4. File Count Consistency (MANDATORY)
-
-**Validation:** PRD file counts MUST match feature.json handoff counts.
-
-```javascript
-const featureHandoff = moduleFeature.handoff.filesToCreate;
-const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests'];
-
-for (const cat of categories) {
-  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
-  const featureCount = featureHandoff[cat]?.length ?? 0;
-
-  if (prdCount !== featureCount) {
-    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but feature.json has ${featureCount}`);
-  }
-}
-```
-
-**Why this matters:**
-- Ensures PRD was derived from the correct feature.json
-- Catches stale PRD files (derived from old version)
-- Validates handoff integrity before ralph-loop
-
-**Fix:**
-- Re-derive PRD from latest feature.json
-- Check that feature.json handoff section is complete
-
----
-
-### 5. File Entry Schema
-
-Each file entry in a category array must have:
-
-```json
-{
-  "path": "src/SmartStack.HumanResources.Domain/Projects/Project.cs",
-  "type": "Entity",
-  "module": "Projects"
-}
-```
-
-**Required Fields:**
-- `path` (string): Absolute or relative path where file will be created
-- `type` (string): File type hint (Entity, Service, Controller, Page, Test, etc.)
-- `module` (string): Module code this file belongs to
-
-**Optional Fields:**
-- `description` (string): Brief description of what the file does
-- `dependencies` (array): Other files this depends on
-
----
-
-## Validation Checklist
-
-Use this checklist when validating PRD files:
-
-| Check | Validation | Status |
-|-------|-----------|--------|
-| **Version** | `$version === "3.0.0"` | PASS/FAIL |
-| **Structure** | `implementation.filesToCreate` exists (not root) | PASS/FAIL |
-| **Categories** | All 7 categories present | PASS/FAIL |
-| **File Counts** | PRD counts match feature.json handoff | PASS/FAIL |
-| **File Schemas** | All files have path, type, module | PASS/FAIL |
-
-**All checks must PASS before proceeding to /ralph-loop**
-
----
-
-## Common Errors & Fixes
-
-### Error 1: Wrong Version
-```
-BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
-```
-**Fix:** Re-run `ss derive-prd` with latest SmartStack.mcp version
-
-### Error 2: filesToCreate at Root Level
-```
-BLOCKING_ERROR: filesToCreate is at ROOT level (wrong structure)
-```
-**Fix:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
-
-### Error 3: Missing Categories
-```
-BLOCKING_ERROR: Missing categories: seedData, tests
-```
-**Fix:**
-- Check feature.json handoff.filesToCreate has all 7 categories
-- Re-derive PRD after fixing feature.json
-- If genuinely no files needed, use empty array: `"seedData": []`
-
-### Error 4: File Count Mismatch
-```
-BLOCKING_ERROR: api: prd has 8 files but feature.json has 12
-```
-**Fix:**
-- PRD is stale (derived from old feature.json)
-- Re-derive PRD from latest feature.json: `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
-
----
-
-## Generation Command Reference
-
-**Derive PRD from feature.json:**
-```bash
-ss derive-prd \
-  --feature docs/{App}/business-analyse/v1.0/feature.json \
-  --output .ralph/prd-{ModuleCode}.json
-```
-
-**Example:**
-```bash
-ss derive-prd \
-  --feature docs/HumanResources/business-analyse/v1.0/feature.json \
-  --output .ralph/prd-Projects.json
-```
-
-**Batch generation for all modules:**
-```bash
-# Typically done in step-05a-handoff.md
-for module in $(modules); do
-  ss derive-prd --feature {module_feature_path} --output .ralph/prd-${module}.json
-done
-```
-
----
-
-## Why PRD Validation Matters
-
-| Risk | Without Validation | With Validation |
-|------|-------------------|-----------------|
-| **Wrong structure** | ralph-loop fails mid-execution | Caught before development starts |
-| **Stale PRD** | Generates code from old spec | Detects version mismatch |
-| **Missing files** | Incomplete implementation | Ensures all layers covered |
-| **Count mismatch** | Silent data loss | Guarantees integrity |
-
-**Bottom line:** Ralph-loop depends on correct PRD structure. Validating upfront saves hours of debugging.
-
----
-
-## Related Files
-
-- `step-05a-handoff.md`: Generates PRD files via `ss derive-prd`
-- `step-05c-ralph-readiness.md`: Validates PRD structure before ralph-loop
-- `feature-schema.json`: Schema for feature.json (source of PRD)
-- `/ralph-loop` skill: Consumes PRD files for implementation
+# PRD v3.0 Structure & Validation Rules
+
+Source: business-analyse step-05-deploy.md
+
+## PRD File Format v3.0
+
+### File Location
+
+```
+.ralph/prd-{moduleCode}.json
+```
+
+Example: `.ralph/prd-Projects.json`, `.ralph/prd-TimeTracking.json`
+
+---
+
+## Structure Requirements
+
+### 1. Version Field (MANDATORY)
+
+```json
+{
+  "$version": "3.0.0"
+}
+```
+
+**Validation:**
+- MUST be exactly `"3.0.0"`
+- BLOCKING if missing or wrong version
+
+**Common Error:**
+```
+BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
+Fix: Re-run ss derive-prd with latest version
+```
+
+---
+
+### 2. Implementation Section (MANDATORY)
+
+**CRITICAL:** `filesToCreate` MUST be under `implementation`, NOT at root level.
+
+**Correct Structure:**
+```json
+{
+  "$version": "3.0.0",
+  "implementation": {
+    "filesToCreate": {
+      "domain": [...],
+      "application": [...],
+      "infrastructure": [...],
+      "api": [...],
+      "frontend": [...],
+      "seedData": [...],
+      "tests": [...],
+      "documentation": [...]
+    }
+  }
+}
+```
+
+**Wrong Structure (v2.x legacy):**
+```json
+{
+  "$version": "3.0.0",
+  "filesToCreate": {  // ❌ WRONG - at root level
+    "domain": [...]
+  }
+}
+```
+
+**Validation:**
+- IF `prd.filesToCreate` exists at root level → BLOCKING ERROR
+- IF `prd.implementation.filesToCreate` missing → BLOCKING ERROR
+
+**Fix Command:**
+```bash
+ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json
+```
+
+---
+
+### 3. Eight Categories (MANDATORY)
+
+All PRD files MUST include these 8 categories under `implementation.filesToCreate`:
+
+| Category | Description | Examples |
+|----------|-------------|----------|
+| **domain** | Domain entities, value objects, domain services | `Project.cs`, `ProjectStatus.cs` |
+| **application** | Application services, DTOs, interfaces | `ProjectService.cs`, `CreateProjectDto.cs` |
+| **infrastructure** | Data access, repositories, EF Core config | `ProjectRepository.cs`, `ProjectConfiguration.cs` |
+| **api** | Controllers, API endpoints | `ProjectsController.cs` |
+| **frontend** | React pages, components, hooks | `ProjectsPage.tsx`, `useProjects.ts` |
+| **seedData** | Seed data classes | `ProjectSeedData.cs` |
+| **tests** | Unit tests, integration tests | `ProjectServiceTests.cs`, `ProjectsControllerTests.cs` |
+| **documentation** | Technical docs, user guides, API specs | `doc-data.ts`, `UserGuide.md`, `api-spec.yaml` |
+
+> **Note `documentation`:** Cette catégorie peut contenir des fichiers générés par le skill `/documentation` après `/ralph-loop`. Elle est obligatoire dans la structure PRD (peut être un tableau vide `[]` si aucune doc n'est prévue, mais DOIT être présente).
+
+**Validation:**
+```javascript
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);
+
+if (missingCategories.length > 0) {
+  BLOCKING_ERROR(`Missing categories: ${missingCategories.join(', ')}`);
+}
+```
+
+**Common Errors:**
+- Missing `tests` category → often forgotten
+- Missing `seedData` category → sometimes omitted for modules without seed data
+- Missing `documentation` category → must be present even if empty
+- Empty arrays allowed (e.g., `"seedData": []`, `"documentation": []`) if genuinely no files needed
+
+---
+
+### 4. File Count Consistency (MANDATORY)
+
+**Validation:** PRD file counts MUST match index.json handoff counts.
+
+```javascript
+const featureHandoff = moduleFeature.handoff.filesToCreate;
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+
+for (const cat of categories) {
+  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd has ${prdCount} files but index.json has ${featureCount}`);
+  }
+}
+```
+
+**Why this matters:**
+- Ensures PRD was derived from the correct index.json
+- Catches stale PRD files (derived from old version)
+- Validates handoff integrity before ralph-loop
+
+**Fix:**
+- Re-derive PRD from latest index.json
+- Check that index.json handoff section is complete
+
+---
+
+### 5. File Entry Schema
+
+Each file entry in a category array must have:
+
+```json
+{
+  "path": "src/SmartStack.HumanResources.Domain/Projects/Project.cs",
+  "type": "Entity",
+  "module": "Projects"
+}
+```
+
+**Required Fields:**
+- `path` (string): Absolute or relative path where file will be created
+- `type` (string): File type hint (Entity, Service, Controller, Page, Test, etc.)
+- `module` (string): Module code this file belongs to
+
+**Optional Fields:**
+- `description` (string): Brief description of what the file does
+- `dependencies` (array): Other files this depends on
+
+---
+
+## Validation Checklist
+
+Use this checklist when validating PRD files:
+
+| Check | Validation | Status |
+|-------|-----------|--------|
+| **Version** | `$version === "3.0.0"` | PASS/FAIL |
+| **Structure** | `implementation.filesToCreate` exists (not root) | PASS/FAIL |
+| **Categories** | All 8 categories present | PASS/FAIL |
+| **File Counts** | PRD counts match index.json handoff.filesToCreate | PASS/FAIL |
+| **File Schemas** | All files have path, type, module | PASS/FAIL |
+
+**All checks must PASS before proceeding to /ralph-loop**
+
+---
+
+## Common Errors & Fixes
+
+### Error 1: Wrong Version
+```
+BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
+```
+**Fix:** Re-run `ss derive-prd` with latest SmartStack.mcp version
+
+### Error 2: filesToCreate at Root Level
+```
+BLOCKING_ERROR: filesToCreate is at ROOT level (wrong structure)
+```
+**Fix:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+
+### Error 3: Missing Categories
+```
+BLOCKING_ERROR: Missing categories: seedData, tests, documentation
+```
+**Fix:**
+- Check index.json handoff.filesToCreate has all 8 categories
+- Re-derive PRD after fixing index.json
+- If genuinely no files needed, use empty array: `"seedData": []`, `"documentation": []`
+
+### Error 4: File Count Mismatch
+```
+BLOCKING_ERROR: api: prd has 8 files but index.json has 12
+```
+**Fix:**
+- PRD is stale (derived from old index.json)
+- Re-derive PRD from latest index.json: `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+
+---
+
+## Generation Command Reference
+
+**Derive PRD from index.json:**
+```bash
+ss derive-prd \
+  --feature docs/{App}/business-analyse/v1.0/index.json \
+  --output .ralph/prd-{ModuleCode}.json
+```
+
+**Example:**
+```bash
+ss derive-prd \
+  --feature docs/HumanResources/business-analyse/v1.0/index.json \
+  --output .ralph/prd-Projects.json
+```
+
+**Batch generation for all modules:**
+```bash
+# Typically done in step-05-deploy.md
+for module in $(modules); do
+  ss derive-prd --feature {module_feature_path} --output .ralph/prd-${module}.json
+done
+```
+
+---
+
+## Why PRD Validation Matters
+
+| Risk | Without Validation | With Validation |
+|------|-------------------|-----------------|
+| **Wrong structure** | ralph-loop fails mid-execution | Caught before development starts |
+| **Stale PRD** | Generates code from old spec | Detects version mismatch |
+| **Missing files** | Incomplete implementation | Ensures all layers covered |
+| **Count mismatch** | Silent data loss | Guarantees integrity |
+
+**Bottom line:** Ralph-loop depends on correct PRD structure. Validating upfront saves hours of debugging.
+
+---
+
+## Related Files
+
+- `step-05-deploy.md`: Generates PRD files via `ss derive-prd`
+- `feature-schema.json`: Schema for index.json (source of PRD)
+- `/ralph-loop` skill: Consumes PRD files for implementation

package/templates/skills/derive-prd/references/readiness-scoring.md

@@ -0,0 +1,104 @@
+# Readiness Scoring Algorithm
+
+> **Used by:** step-00-validate (section 4: Calculate Readiness Score)
+> **Purpose:** Evaluate module readiness for handoff based on acceptance criteria from validation-checklist.md.
+
+---
+
+## Algorithm
+
+For each module, evaluate all acceptance criteria (AC-01 to AC-17) from `references/acceptance-criteria.md`.
+
+### Score Calculation
+
+```javascript
+const blockingACs = ['AC-01', 'AC-02', 'AC-03', 'AC-04', 'AC-05', 'AC-06', 'AC-07',
+                     'AC-08', 'AC-09', 'AC-10', 'AC-11', 'AC-12', 'AC-13',
+                     'AC-15', 'AC-16', 'AC-17'];  // 16 blocking
+const nonBlockingACs = ['AC-14'];  // 1 non-blocking (warning only)
+
+// Count passes
+const blockingPassed = blockingACs.filter(ac => results[ac] === 'PASS').length;
+const blockingTotal = blockingACs.length;
+const nonBlockingPassed = nonBlockingACs.filter(ac => results[ac] === 'PASS').length;
+const nonBlockingTotal = nonBlockingACs.length;
+
+// Scores
+const blockingScore = (blockingPassed / blockingTotal) * 100;  // Must be 100%
+const nonBlockingScore = (nonBlockingPassed / nonBlockingTotal) * 100;  // Warn if < 80%
+```
+
+### Gate Rules
+
+| Condition | Action |
+|-----------|--------|
+| Blocking score = 100% | PASS — module ready for handoff |
+| Blocking score < 100% | BLOCKING — list failed ACs, require fix |
+| Non-blocking score >= 80% | OK — proceed normally |
+| Non-blocking score < 80% | WARNING — suggest fixes but don't block |
+
+---
+
+## Output Format
+
+### Per-Module Result
+
+```javascript
+{
+  moduleCode: "Employees",
+  blockingScore: 100,        // percentage
+  blockingPassed: 16,
+  blockingTotal: 16,
+  nonBlockingScore: 100,
+  nonBlockingPassed: 1,
+  nonBlockingTotal: 1,
+  ready: true,
+  failedACs: [],             // empty if ready
+  warnings: []               // non-blocking failures
+}
+```
+
+### Readiness Table
+
+```
+┌──────────────┬──────────┬────────────┬──────────────┬────────┐
+│ Module       │ Status   │ Blocking   │ Non-blocking │ Ready  │
+├──────────────┼──────────┼────────────┼──────────────┼────────┤
+│ Employees    │ consol.  │ 16/16 100% │ 1/1 100%     │ YES    │
+│ Absences     │ consol.  │ 14/16  88% │ 1/1 100%     │ NO     │
+└──────────────┴──────────┴────────────┴──────────────┴────────┘
+```
+
+### Failure Detail (when blocked)
+
+```
+Module "Absences" — 2 blocking ACs FAILED:
+
+  FAIL AC-05: wireframes >= 1 = 0 (min: 1)
+    Recovery: Re-run /business-analyse step-03 wireframe generation
+
+  FAIL AC-09: seedDataCore 9 arrays = 7 (min: 9)
+    Recovery: Re-run /business-analyse step-03 seedDataCore transform
+```
+
+---
+
+## Recovery Actions
+
+Each failed AC has a specific recovery action (from `references/acceptance-criteria.md`):
+
+| AC | Recovery |
+|----|----------|
+| AC-01/02 | Re-run step-03 entity specification |
+| AC-03/04 | Re-run step-03 use case / functional requirements |
+| AC-05/06/07 | Re-run step-03 wireframe generation |
+| AC-08 | Re-run step-03 section definition |
+| AC-09 | Re-run step-03 seedDataCore transform |
+| AC-10 | Auto-fix: wrap in array |
+| AC-11 | Re-run step-03 API endpoints |
+| AC-12 | Re-run step-03 messages |
+| AC-13 | Re-run step-03 validations |
+| AC-14 | Auto-fix: rename fields (non-blocking) |
+| AC-15 | Auto-fix: wrap string in array |
+| AC-16 | Auto-fix: copy description to message |
+| AC-17 | Re-run step-03 gherkin |