@atlashub/smartstack-cli 4.48.0 → 4.50.0

package/templates/skills/business-analyse/steps/step-04-consolidate.md

@@ -330,6 +330,175 @@ Les types possibles : `functional`, `business-rule`, `performance`, `security`.
 
 Les critères d'acceptation sont écrits dans `validation.json` au même niveau que `globalRiskAssessment`.
 
+### 7ter. Naming Audit (MANDATORY)
+
+> **Challenge all names before final approval.** Every code, label, and route generated
+> during the BA must be reviewed for coherence, convention compliance, and clarity.
+
+**7ter-a. Collect all names from the BA:**
+
+```javascript
+const namingRegistry = {
+  application: {
+    label: application_name,
+    code: applicationCode,              // PascalCase
+    route: toKebabCase(applicationCode)  // kebab-case
+  },
+  modules: completedModules.map(m => ({
+    label: m.name,
+    code: m.code,                        // PascalCase
+    route: toKebabCase(m.code)           // kebab-case
+  })),
+  entities: completedModules.flatMap(m =>
+    m.entities.map(e => ({
+      name: e.name,                      // PascalCase (C# class name)
+      module: m.code,
+      tableName: e.tableName || pluralize(e.name)  // Plural convention
+    }))
+  ),
+  permissionRoots: [...new Set(
+    permissionPaths.map(p => p.path.split('.').slice(0, 2).join('.'))
+  )]
+};
+```
+
+**7ter-b. Display naming recap table:**
+
+```
+═══════════════════════════════════════════════════════════════
+  NAMING AUDIT — {application_name}
+═══════════════════════════════════════════════════════════════
+
+APPLICATION
+| Label | Code (PascalCase) | Route (kebab-case) |
+|-------|-------------------|--------------------|
+| {application_name} | {applicationCode} | /{route} |
+
+MODULES
+| # | Label | Code (PascalCase) | Route (kebab-case) |
+|---|-------|-------------------|--------------------|
+{for each module: index | label | code | /app-route/module-route}
+
+ENTITIES
+| Entity (PascalCase) | Module | Table (plural) |
+|----------------------|--------|----------------|
+{for each entity: name | module | tableName}
+
+PERMISSION ROOTS
+{for each root: path}
+═══════════════════════════════════════════════════════════════
+```
+
+**7ter-c. Coherence checks:**
+
+```javascript
+const namingIssues = [];
+
+// 1. Duplicate entity names across modules
+const entityNames = namingRegistry.entities.map(e => e.name);
+const duplicates = entityNames.filter((n, i) => entityNames.indexOf(n) !== i);
+if (duplicates.length > 0) {
+  namingIssues.push({ severity: "ERROR", issue: `Duplicate entity names: ${[...new Set(duplicates)].join(', ')}` });
+}
+
+// 2. Module code vs label coherence (code should derive logically from label)
+for (const mod of namingRegistry.modules) {
+  if (!mod.code || mod.code.length < 2) {
+    namingIssues.push({ severity: "ERROR", issue: `Module "${mod.label}" has invalid code: "${mod.code}"` });
+  }
+}
+
+// 3. Permission root alignment with module codes
+for (const root of namingRegistry.permissionRoots) {
+  const [appSegment, moduleSegment] = root.split('.');
+  const matchingModule = namingRegistry.modules.find(m =>
+    m.code.toLowerCase() === moduleSegment.toLowerCase()
+  );
+  if (!matchingModule) {
+    namingIssues.push({ severity: "WARNING", issue: `Permission root "${root}" has no matching module code` });
+  }
+}
+
+// 4. Route collision detection
+const allRoutes = namingRegistry.modules.map(m =>
+  `/${namingRegistry.application.route}/${m.route}`
+);
+const routeDuplicates = allRoutes.filter((r, i) => allRoutes.indexOf(r) !== i);
+if (routeDuplicates.length > 0) {
+  namingIssues.push({ severity: "ERROR", issue: `Route collisions: ${routeDuplicates.join(', ')}` });
+}
+```
+
+**7ter-d. MCP validation:**
+
+```
+mcp__smartstack__validate_conventions({
+  checks: ["tables"],
+  context: {
+    applicationCode: applicationCode,
+    modules: namingRegistry.modules.map(m => m.code),
+    entities: namingRegistry.entities.map(e => e.name)
+  }
+})
+
+→ Merge MCP findings into namingIssues[]
+```
+
+**7ter-e. Present findings and confirm:**
+
+```
+IF namingIssues.length > 0:
+  Display issues table:
+  | # | Severity | Issue |
+  |---|----------|-------|
+  {for each issue}
+```
+
+Ask via AskUserQuestion:
+```
+question: "{language == 'fr'
+  ? 'Validez-vous les noms ci-dessus pour l\\'ensemble de l\\'application ?'
+  : 'Do you approve all the names above for the entire application?'}"
+header: "Naming Audit"
+options:
+  - label: "{language == 'fr' ? 'Approuvé' : 'Approved'}"
+    description: "{language == 'fr' ? 'Tous les noms sont corrects' : 'All names are correct'}"
+  - label: "{language == 'fr' ? 'Renommer certains éléments' : 'Rename some elements'}"
+    description: "{language == 'fr' ? 'Corriger des noms avant de finaliser' : 'Fix names before finalizing'}"
+```
+
+**IF "Renommer certains éléments":**
+
+Ask via AskUserQuestion (open-ended):
+```
+question: "{language == 'fr'
+  ? 'Quels éléments souhaitez-vous renommer ? (ex: \"Module Ventes → Commerce\", \"Entity Invoice → BillingDocument\")'
+  : 'Which elements do you want to rename? (e.g., \"Module Sales → Commerce\", \"Entity Invoice → BillingDocument\")'}"
+header: "Renaming"
+```
+
+Process user response:
+1. Parse rename instructions
+2. Update `applicationCode`, module codes, entity names, permission paths accordingly in JSON files via ba-writer
+3. Re-run 7ter-c and 7ter-d checks on updated names
+4. Re-display the naming recap table for final confirmation
+
+**IF "Approuvé":**
+→ Store naming audit result in `validation.json`:
+```javascript
+ba-writer.enrichSection({
+  featureId: {feature_id},
+  section: "namingAudit",
+  data: {
+    auditedAt: now(),
+    issues: namingIssues,
+    approved: true,
+    renames: []  // or list of applied renames
+  }
+});
+```
+→ Continue to section 8
+
 ### 8. Consolidation Summary Display
 
 ```
@@ -449,6 +618,7 @@ ba-writer.enrichSection({
       `E2E flows: ${e2eFlows.length} identified`,
       `Global risk: ${risks.length > 0 ? 'MEDIUM' : 'LOW'}`,
       `Semantic checks: PASSED`,
+      `Naming audit: ${namingIssues.length} issues found, APPROVED`,
       `Client approval: APPROVED`
     ]
   }
@@ -508,6 +678,7 @@ BA workflow complete. Next steps:
 - ✓ No circular dependencies
 - ✓ Permission coherence validated
 - ✓ Semantic checks: 0 errors
+- ✓ Naming audit completed and approved
 - ✓ Client approval obtained (or auto-approved for single module)
 - ✓ Consolidation section written to validation.json
 - ✓ Status updated to "consolidated"

package/templates/skills/business-analyse-develop/references/quality-gates.md

@@ -14,8 +14,9 @@
 | MCP code review | `review_code` | YES (if perm mismatch) | After security |
 | MCP conventions | `validate_conventions` | NO (report) | After code review |
 | MCP test conventions | `validate_test_conventions` | NO (report) | After conventions |
-| BR coverage | grep implementation | YES (100%) | After MCP gates |
+| BR coverage | grep implementation (enriched) | YES (100%) | After MCP gates |
 | File reconciliation | compare expectedFiles vs disk | YES | After BR coverage |
+| Spec fidelity | compare specs vs code | NO (report) | After file reconciliation |
 | Stub test detection | grep stub patterns | YES | During test gate |
 
 ## Stub Test Patterns (AUTO-REJECT)
@@ -66,5 +67,94 @@ BR coverage check
     ↓ (100%)
 File reconciliation
     ↓ (all present)
+Spec fidelity (non-blocking report)
+    ↓ (report)
 MODULE COMPLETE
 ```
+
+## BR Coverage — Enriched Verification
+
+When `prd.specificationFiles` is present and companion files are available, the BR coverage gate uses the enriched `brToCodeMapping` (with `statement`, `formula`, `example`) for verification.
+
+**Standard check:** grep each `brToCodeMapping[].ruleId` in the codebase to confirm implementation.
+
+**Enriched fix context:** When a BR is NOT covered, provide full context for the fix:
+
+```
+MISSING BR IMPLEMENTATION:
+  Rule: {ruleId}
+  Statement: {statement}
+  Example: {example}
+  Formula: {formula}
+  Entities: {entities[]}
+  Category: {category}
+  Severity: {severity}
+  Expected in: {implementationPoints[].component} ({implementationPoints[].layer})
+```
+
+This gives `/apex` or the developer the complete context to implement the missing BR without re-reading the BA artifacts.
+
+## Gate: Specification Fidelity (non-blocking report)
+
+> **When:** After file reconciliation. **Blocking:** NO (report only).
+> **Requires:** `prd.specificationFiles` present with companion files.
+
+Compares generated code against companion specification files to measure implementation fidelity.
+
+**Checks:**
+
+```javascript
+if (prd.specificationFiles) {
+  const specsDir = '.ralph';
+  const entitiesSpec = readJSON(`${specsDir}/${prd.specificationFiles.entities}`);
+  const rulesSpec = readJSON(`${specsDir}/${prd.specificationFiles.rules}`);
+  let totalChecks = 0, passedChecks = 0;
+
+  // 1. Entity property coverage
+  for (const entity of (entitiesSpec.entities || [])) {
+    const entityFile = findFile(`src/**/Domain/**/${entity.name}.cs`);
+    if (entityFile) {
+      const content = readFile(entityFile);
+      for (const attr of (entity.attributes || [])) {
+        totalChecks++;
+        if (content.includes(attr.name)) passedChecks++;
+        else console.warn(`SPEC DRIFT: ${entity.name}.${attr.name} not found in ${entityFile}`);
+      }
+    }
+  }
+
+  // 2. Validator coverage for BR-VAL-*
+  for (const rule of (rulesSpec.rules || [])) {
+    if (rule.id?.startsWith('BR-VAL-')) {
+      totalChecks++;
+      const validatorFiles = findFiles(`src/**/Validators/**/*Validator.cs`);
+      const found = validatorFiles.some(f => readFile(f).includes(rule.id));
+      if (found) passedChecks++;
+      else console.warn(`SPEC DRIFT: ${rule.id} (${rule.statement?.slice(0, 50)}...) has no Validator implementation`);
+    }
+  }
+
+  // 3. Calculation coverage for BR-CALC-*
+  for (const rule of (rulesSpec.rules || [])) {
+    if (rule.id?.startsWith('BR-CALC-') && rule.formula) {
+      totalChecks++;
+      const serviceFiles = findFiles(`src/**/Services/**/*Service.cs`);
+      const found = serviceFiles.some(f => readFile(f).includes(rule.id));
+      if (found) passedChecks++;
+      else console.warn(`SPEC DRIFT: ${rule.id} formula "${rule.formula}" has no Service implementation`);
+    }
+  }
+
+  const fidelityScore = totalChecks > 0 ? Math.round((passedChecks / totalChecks) * 100) : 100;
+  console.log(`SPEC FIDELITY: ${fidelityScore}% (${passedChecks}/${totalChecks} checks passed)`);
+}
+```
+
+**Output:**
+```
+SPEC FIDELITY: 92% (23/25 checks passed)
+  DRIFT: Employee.TerminationDate not found in Employee.cs
+  DRIFT: BR-CALC-002 formula "netSalary = grossSalary - deductions" has no Service implementation
+```
+
+This gate does NOT block — it provides visibility into specification coverage gaps.

package/templates/skills/business-analyse-develop/steps/step-01-task.md

@@ -66,6 +66,149 @@ If `{currentPrdPath}` exists:
    - Write back to `{currentPrdPath}`
    - **Run CATEGORY COMPLETENESS CHECK (section 4b) before proceeding**
    - Skip directly to section 5 (find next task)
+2b. **v3 filesToCreate PATH:** If `$version === "3.0.0"` AND `implementation.filesToCreate` exists AND NO `tasks[]`:
+   → Transform filesToCreate into tasks[]:
+
+   ```javascript
+   const ftc = prd.implementation.filesToCreate;
+   const tasks = [];
+   let taskId = 1;
+
+   // CATEGORY ORDER: domain → infrastructure → application → api → seedData → frontend → test → documentation
+   const categoryOrder = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'tests', 'documentation'];
+
+   // Load companion specs if available (for rich acceptance criteria)
+   const specFiles = prd.specificationFiles || {};
+   const specsDir = '.ralph';
+   let specEntities = null, specRules = null, specUsecases = null, specScreens = null, specPermissions = null;
+   try {
+     if (specFiles.entities) specEntities = readJSON(`${specsDir}/${specFiles.entities}`);
+     if (specFiles.rules) specRules = readJSON(`${specsDir}/${specFiles.rules}`);
+     if (specFiles.usecases) specUsecases = readJSON(`${specsDir}/${specFiles.usecases}`);
+     if (specFiles.screens) specScreens = readJSON(`${specsDir}/${specFiles.screens}`);
+     if (specFiles.permissions) specPermissions = readJSON(`${specsDir}/${specFiles.permissions}`);
+   } catch (e) { /* companion files absent — fallback to generic AC */ }
+
+   function deriveAcceptanceCriteria(file, category, prd) {
+     const fileName = (file.path || file).split('/').pop().replace(/\.\w+$/, '');
+
+     // If no companion specs available, fallback to generic AC
+     if (!specEntities && !specRules) {
+       return `File ${file.path || file} exists and compiles`;
+     }
+
+     switch (category) {
+       case 'domain': {
+         const entityName = fileName;
+         const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+         if (entity && entity.attributes) {
+           const attrs = entity.attributes.map(a => `${a.name}:${a.type}`).join(', ');
+           const rels = (entity.relationships || []).map(r => `${r.type} ${r.target}`).join(', ');
+           return `Entity ${entityName} with attributes [${attrs}]${rels ? '. Relations: [' + rels + ']' : ''}`;
+         }
+         break;
+       }
+       case 'application': {
+         const linkedBRs = (prd.brToCodeMapping || [])
+           .filter(br => br.implementationPoints?.some(ip => ip.component?.includes(fileName)))
+           .map(br => `${br.ruleId}: ${br.statement || br.title}`);
+         const linkedUCs = (file.linkedUCs || []).join(', ');
+         if (linkedBRs.length > 0 || linkedUCs) {
+           const parts = [];
+           if (linkedBRs.length > 0) parts.push(`Implements BRs: [${linkedBRs.join('; ')}]`);
+           if (linkedUCs) parts.push(`Handles UCs: [${linkedUCs}]`);
+           return parts.join('. ');
+         }
+         break;
+       }
+       case 'infrastructure': {
+         const entityName = fileName.replace('Configuration', '');
+         const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+         if (entity && entity.attributes) {
+           const props = entity.attributes.map(a => a.name).join(', ');
+           return `EF Config for ${entityName}. Attributes: [${props}]`;
+         }
+         break;
+       }
+       case 'api': {
+         const entityName = fileName.replace('Controller', '');
+         const endpoints = (prd.apiEndpointSummary || [])
+           .filter(ep => ep.operation?.includes(entityName))
+           .map(ep => `${ep.method} ${ep.route}`);
+         const perms = (specPermissions?.permissionPaths || [])
+           .filter(p => p.toLowerCase().includes(entityName.toLowerCase()))
+           .slice(0, 5);
+         const parts = [`Controller ${entityName}`];
+         if (endpoints.length > 0) parts.push(`Endpoints: [${endpoints.join(', ')}]`);
+         if (perms.length > 0) parts.push(`Permissions: [${perms.join(', ')}]`);
+         return parts.join('. ');
+       }
+       case 'frontend': {
+         const screen = (specScreens?.screens || []).find(s =>
+           fileName.toLowerCase().includes(s.code?.toLowerCase() || s.name?.toLowerCase() || '')
+         );
+         if (screen) {
+           const parts = [file.type || 'Page'];
+           if (screen.columns) parts.push(`columns [${screen.columns.map(c => c.key || c.name || c).join(', ')}]`);
+           if (screen.filters) parts.push(`filters [${screen.filters.map(f => f.key || f.name || f).join(', ')}]`);
+           if (screen.actions) parts.push(`actions [${screen.actions.map(a => a.key || a.name || a).join(', ')}]`);
+           if (screen.kpis) parts.push(`KPIs [${screen.kpis.map(k => k.label || k.name || k).join(', ')}]`);
+           return `${parts.join(' with ')}`;
+         }
+         break;
+       }
+       case 'seedData': {
+         if (file.category === 'business') {
+           const entityName = fileName.replace('SeedData', '');
+           const entity = (specEntities?.entities || []).find(e => e.name === entityName);
+           if (entity?.seedValues) {
+             const names = entity.seedValues.map(v => v.name || v.label || v.code).filter(Boolean).slice(0, 5);
+             return `Seeds ${entityName} with ${entity.seedValues.length} values: [${names.join(', ')}]`;
+           }
+         }
+         break;
+       }
+       case 'test': case 'tests': {
+         const linkedBRs = (prd.brToCodeMapping || [])
+           .filter(br => br.implementationPoints?.some(ip =>
+             ip.layer === 'Domain' || ip.layer === 'Application'
+           ))
+           .map(br => br.ruleId);
+         const linkedUCs = (file.linkedUCs || []);
+         const parts = [];
+         if (linkedBRs.length > 0) parts.push(`Covers BRs: [${linkedBRs.join(', ')}]`);
+         if (linkedUCs.length > 0) parts.push(`Covers UCs: [${linkedUCs.join(', ')}]`);
+         if (parts.length > 0) return parts.join('. ');
+         break;
+       }
+     }
+     // Fallback: generic AC
+     return `File ${file.path || file} exists and compiles`;
+   }
+
+   for (const category of categoryOrder) {
+     const files = ftc[category] || [];
+     for (const file of files) {
+       tasks.push({
+         id: `T${String(taskId++).padStart(3, '0')}`,
+         description: `Create ${file.type || category}: ${(file.path || file).split('/').pop()}`,
+         status: 'pending',
+         category: category === 'tests' ? 'test' : category,  // normalize
+         dependencies: [],  // implicit ordering via category
+         acceptance_criteria: deriveAcceptanceCriteria(file, category === 'tests' ? 'test' : category, prd),
+         path: file.path || file,
+         started_at: null, completed_at: null, iteration: null,
+         commit_hash: null, files_changed: [], validation: null, error: null
+       });
+     }
+   }
+
+   prd.tasks = tasks;
+   prd.config = { current_iteration: 1, max_iterations: 50 };
+   writeJSON(currentPrdPath, prd);
+   ```
+   → Run CATEGORY COMPLETENESS CHECK (section 4b) — will detect if seedData is missing
+   → Skip to section 5 (find next task)
 3. **v2 legacy:** If `$version === "2.0.0"` → find next eligible task (section 5)
 4. **FORMAT A (deprecated):** If `.project && .requirements && !.$version` → run `transformPrdJsonToRalphV2()` → section 5
 
@@ -120,7 +263,10 @@ Check for BA handoff source (priority):
 3. Markdown handoff: `find . -path "*development-handoff*" -name "*.md"`
 4. Direct task from `{task_description}`
 
-Generate **3-30 subtasks** by category (domain → infrastructure → application → api → frontend → i18n → test → validation).
+Generate **3-30 subtasks** by category (domain → infrastructure → application → api → seedData → frontend → i18n → test → validation).
+
+**seedData category is MANDATORY** — generates navigation entries, permissions, roles, and the IClientSeedDataProvider.
+Without seedData tasks, modules are invisible in the UI (no menu, no permissions, no RBAC).
 
 ## 3. Create prd.json
 

package/templates/skills/business-analyse-handoff/references/acceptance-criteria.md

@@ -51,6 +51,12 @@ These verify data that `/business-analyse-handoff` step-01 generates:
 | AC-09 | BR-to-code mapping present | 1 | `handoff.brToCodeMapping[]` | YES |
 | AC-10 | API endpoint summary present | 1 | `handoff.apiEndpointSummary[]` | YES |
 | AC-11 | SeedData entries have category | ALL | `handoff.filesToCreate.seedData[].category` | YES |
+| AC-12 | `specificationFiles` present with 5 paths | 5 | `handoff.specificationFiles` | YES |
+| AC-13 | Companion entities file exists and count matches source | match | `.ralph/prd-{module}.entities.json` | YES |
+| AC-14 | Companion rules file exists and count matches source | match | `.ralph/prd-{module}.rules.json` | YES |
+| AC-15 | Companion usecases file exists and count matches source | match | `.ralph/prd-{module}.usecases.json` | YES |
+| AC-16 | Companion screens file exists (if screens.json exists) | exists | `.ralph/prd-{module}.screens.json` | YES |
+| AC-17 | Each `brToCodeMapping[].statement` non-empty | ALL | `handoff.brToCodeMapping[].statement` | YES |
 
 ---
 
@@ -240,11 +246,51 @@ if (noCat.length > 0) {
   console.error('FAIL: AC-11: ' + noCat.length + ' seedData entries missing category field');
 }
 
+// AC-12: specificationFiles present with 5 paths
+const specFiles = handoff.specificationFiles || {};
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+const missingSpecs = specKeys.filter(k => !specFiles[k]);
+if (missingSpecs.length > 0) {
+  fails.push('AC-12: specificationFiles missing keys: ' + missingSpecs.join(', '));
+  console.error('FAIL: AC-12: specificationFiles missing keys: ' + missingSpecs.join(', '));
+}
+
+// AC-13 to AC-16: Companion files exist and counts match
+const ralphDir = path.dirname(process.argv[1]);
+const companionChecks = [
+  { ac: 'AC-13', key: 'entities', arrayKey: 'entities' },
+  { ac: 'AC-14', key: 'rules', arrayKey: 'rules' },
+  { ac: 'AC-15', key: 'usecases', arrayKey: 'useCases' },
+  { ac: 'AC-16', key: 'screens', arrayKey: 'screens' }
+];
+for (const check of companionChecks) {
+  const companionPath = specFiles[check.key] ? path.join(ralphDir, specFiles[check.key]) : null;
+  if (companionPath && fs.existsSync(companionPath)) {
+    const companionData = JSON.parse(fs.readFileSync(companionPath, 'utf-8'));
+    const arr = companionData[check.arrayKey] || companionData[check.arrayKey.toLowerCase()] || [];
+    if (arr.length === 0 && check.ac !== 'AC-16') {
+      fails.push(check.ac + ': companion ' + check.key + ' file is empty');
+      console.error('FAIL: ' + check.ac + ': companion ' + check.key + ' file has 0 entries');
+    }
+  } else if (companionPath) {
+    fails.push(check.ac + ': companion file missing: ' + specFiles[check.key]);
+    console.error('FAIL: ' + check.ac + ': companion file not found: ' + specFiles[check.key]);
+  }
+}
+
+// AC-17: Each brToCodeMapping[].statement non-empty
+const brMapping = handoff.brToCodeMapping || [];
+const emptyStatements = brMapping.filter(br => !br.statement || br.statement.trim() === '');
+if (emptyStatements.length > 0) {
+  fails.push('AC-17: ' + emptyStatements.length + ' BRs with empty statement');
+  console.error('FAIL: AC-17: ' + emptyStatements.length + ' brToCodeMapping entries have empty statement: ' + emptyStatements.slice(0, 3).map(b => b.ruleId).join(', '));
+}
+
 if (fails.length > 0) {
   console.error('\\nBLOCKING: ' + fails.length + ' output acceptance criteria FAILED');
   process.exit(1);
 }
-console.log('PASS: All output acceptance criteria met (AC-08 to AC-11)');
+console.log('PASS: All output acceptance criteria met (AC-08 to AC-17)');
 " "$MODULE_JSON"
 ```
 
@@ -264,3 +310,9 @@ console.log('PASS: All output acceptance criteria met (AC-08 to AC-11)');
 | AC-09 | Re-run `/business-analyse-handoff` step-01 transform (BR mapping) |
 | AC-10 | Re-run `/business-analyse-handoff` step-01 transform (API endpoints) |
 | AC-11 | Re-run `/business-analyse-handoff` step-01 transform (seedData categories) |
+| AC-12 | Re-run `/business-analyse-handoff` step-01 transform (specificationFiles missing) |
+| AC-13 | Re-run `/business-analyse-handoff` step-01 transform (entities companion missing/empty) |
+| AC-14 | Re-run `/business-analyse-handoff` step-01 transform (rules companion missing/empty) |
+| AC-15 | Re-run `/business-analyse-handoff` step-01 transform (usecases companion missing/empty) |
+| AC-16 | Re-run `/business-analyse-handoff` step-01 transform (screens companion missing) |
+| AC-17 | Re-run `/business-analyse-handoff` step-01 transform (BR statements empty — copy from rules.json) |

package/templates/skills/business-analyse-handoff/references/handoff-file-templates.md

@@ -153,3 +153,45 @@ From `screens.json > screens[]` and `usecases.json > useCases[]`:
 
 Include: Technical documentation data, API specification files, user guides.
 This category can be an empty array `[]` if no documentation is planned at this stage. It will be populated by the `/documentation` skill after `/business-analyse-develop` completes.
+
+## 4.9 Specification Files (Companion Files)
+
+> **Purpose:** Enable `/apex` and `/business-analyse-develop` to load full BA specifications per layer, avoiding monolithic context loading.
+
+Each PRD MUST include a `specificationFiles` object referencing 5 companion files:
+
+```json
+"specificationFiles": {
+  "entities": "prd-{moduleCode}.entities.json",
+  "rules": "prd-{moduleCode}.rules.json",
+  "usecases": "prd-{moduleCode}.usecases.json",
+  "screens": "prd-{moduleCode}.screens.json",
+  "permissions": "prd-{moduleCode}.permissions.json"
+}
+```
+
+### Naming Convention
+
+`prd-{moduleCode}.{section}.json` — all files colocated in `.ralph/` alongside the PRD.
+
+| File | Source | Content |
+|------|--------|---------|
+| `prd-{moduleCode}.entities.json` | `{moduleDir}/entities.json` | VERBATIM copy |
+| `prd-{moduleCode}.rules.json` | `{moduleDir}/rules.json` | VERBATIM copy |
+| `prd-{moduleCode}.usecases.json` | `{moduleDir}/usecases.json` | VERBATIM copy |
+| `prd-{moduleCode}.screens.json` | `{moduleDir}/screens.json` | VERBATIM copy |
+| `prd-{moduleCode}.permissions.json` | `{moduleDir}/permissions.json` | VERBATIM copy |
+
+### Rules
+
+- **VERBATIM copy:** Each companion file is a 1:1 copy of the BA source file. Zero transformation, zero filtering.
+- **Colocated:** All companion files live in `.ralph/` alongside the PRD file.
+- **Mandatory:** All 5 companion files MUST be generated for every module PRD.
+- **Layer loading:** `/apex` loads only the companion files needed per layer (see loading plan below).
+
+| Layer | Files loaded | Estimated context |
+|-------|-------------|-------------------|
+| Layer 0 (domain) | `entities.json` | ~200-400 lines |
+| Layer 1 (seed) | `entities.json` + `permissions.json` | ~300-500 lines |
+| Layer 2 (backend) | `rules.json` + `usecases.json` | ~300-600 lines |
+| Layer 3 (frontend) | `screens.json` + `usecases.json` | ~300-500 lines |

package/templates/skills/business-analyse-handoff/references/handoff-mappings.md

@@ -12,6 +12,13 @@ Generate complete mapping for each BR:
     {
       "ruleId": "BR-VAL-001",
       "title": "Order total must equal sum of item prices",
+      "statement": "The order total amount must equal the sum of all order item prices multiplied by their quantities",
+      "example": "Order with 3 items at $10, $20, $30 → total must be $60. If total = $50 → validation error",
+      "formula": null,
+      "conditions": [],
+      "entities": ["Order", "OrderItem"],
+      "category": "validation",
+      "sectionCode": "orders",
       "module": "{moduleCode}",
       "severity": "critical",
       "implementationPoints": [
@@ -27,7 +34,14 @@ Generate complete mapping for each BR:
 
 For each BR include:
 - **ruleId**: Reference to `rules.json > rules[].id`
-- **title**: The rule statement
+- **title**: Short descriptive title
+- **statement**: VERBATIM copy of `rules.json > rules[].statement` — the full rule text, NOT a paraphrase
+- **example**: VERBATIM copy of `rules.json > rules[].example` — concrete example illustrating the rule (null if absent)
+- **formula**: VERBATIM copy of `rules.json > rules[].formula` — formula for BR-CALC-* rules (null if absent)
+- **conditions**: VERBATIM copy of `rules.json > rules[].conditions[]` — conditions of applicability (empty array if absent)
+- **entities**: Array of entity names this rule applies to (from `rules.json > rules[].entities[]` or inferred from rule context)
+- **category**: Rule category from `rules.json > rules[].category` — one of: validation, calculation, workflow, security, data
+- **sectionCode**: Section this rule belongs to (from `rules.json > rules[].sectionCode` or inferred)
 - **module**: Which module it belongs to
 - **severity**: From `rule.severity` (blocking, info, etc.) mapped to "critical", "high", "medium", "low"
 - **implementationPoints**: Array of {layer, component, method, implementation}