@atlashub/smartstack-cli 4.48.0 → 4.49.0

package/templates/skills/apex/steps/step-03d-layer3-frontend.md

@@ -9,6 +9,38 @@ parent_step: steps/step-03-execute.md
 
 # Layer 3 — Frontend (Pages + I18n + Documentation)
 
+### Companion Specs Loading (delegate mode)
+
+```javascript
+if (delegate_mode && specification_loading_plan) {
+  const specsDir = path.dirname(delegate_prd_path);
+  // Layer 3 loads: screens + usecases companions
+  for (const file of specification_loading_plan.layer3_frontend) {
+    const specPath = path.join(specsDir, file);
+    if (fileExists(specPath)) {
+      const specData = readJSON(specPath);
+      if (specData.screens) {
+        // Full screen definitions: columns[], fields[], filters[], actions[], kpis[]
+        // Use for: DataTable columns, form fields, filter configs, action buttons, dashboard KPIs
+        console.log(`Loaded screens: ${specData.screens.length} screen specs with columns/fields/filters`);
+      }
+      if (specData.useCases || specData.usecases) {
+        const ucs = specData.useCases || specData.usecases;
+        // UC steps inform form validation, navigation flows, error states
+        console.log(`Loaded usecases: ${ucs.length} use cases for form flows`);
+      }
+    }
+  }
+}
+```
+
+> When companion specs are loaded:
+> - **List pages**: use `screen.columns[]` for exact DataTable column definitions (key, label, type, sortable)
+> - **Form pages**: use `screen.fields[]` for exact form field definitions (name, type, required, validation)
+> - **Filter configs**: use `screen.filters[]` for search/filter UI generation
+> - **Dashboard pages**: use `screen.kpis[]` for KPI card and chart definitions
+> - **Actions**: use `screen.actions[]` for action buttons (create, export, bulk operations)
+
 ### ⛔ HARD RULE — /ui-components is NON-NEGOTIABLE (read BEFORE any Layer 3 action)
 
 > **VIOLATION CHECK:** If ANY .tsx page file was created by Write tool WITHOUT

package/templates/skills/application/references/backend-controller-hierarchy.md

@@ -38,14 +38,24 @@ Api/Controllers/
 The generated controller uses NavRoute attribute:
 
 ```csharp
-[NavRoute("{full_path}")]
 [ApiController]
-[Authorize]
+[NavRoute("{full_path}")]
+[Microsoft.AspNetCore.Authorization.Authorize]
+[Produces("application/json")]
+[Tags("{EntityNamePlural}")]
 public class {EntityName}Controller : ControllerBase
 {
+    private readonly ISender _mediator;
+
+    public {EntityName}Controller(ISender mediator) => _mediator = mediator;
+
     [HttpGet]
-    [RequirePermission(Permissions.{Application}.{Module}.Read)]
-    public async Task<ActionResult<IEnumerable<{EntityName}Dto>>> GetAll() { ... }
+    [RequirePermission(Permissions.{Application}.{Module}.View)]
+    [ProducesResponseType(typeof(List<{EntityName}ListDto>), StatusCodes.Status200OK)]
+    [ProducesResponseType(StatusCodes.Status401Unauthorized)]
+    [ProducesResponseType(StatusCodes.Status403Forbidden)]
+    public async Task<ActionResult<List<{EntityName}ListDto>>> GetAll(CancellationToken ct)
+        => Ok(await _mediator.Send(new Get{EntityNamePlural}Query(), ct));
 
     // ... other CRUD methods
 }

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}

package/templates/skills/business-analyse-handoff/references/prd-generation.md

@@ -208,6 +208,64 @@ Each file entry in a category array must have:
 
 ---
 
+### 6. Specification Files (MANDATORY)
+
+Each PRD MUST include a `specificationFiles` object and 5 companion files in `.ralph/`:
+
+```json
+{
+  "$version": "3.0.0",
+  "implementation": { "filesToCreate": { /* 8 categories */ } },
+  "brToCodeMapping": [ /* enriched with statement, example, formula */ ],
+  "apiEndpointSummary": [ /* ... */ ],
+  "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"
+  }
+}
+```
+
+**Companion files** are VERBATIM copies of BA source files, colocated in `.ralph/`:
+
+```
+.ralph/
+  prd-Employees.json                  # PRD manifest (compact)
+  prd-Employees.entities.json         # VERBATIM copy of entities.json
+  prd-Employees.rules.json            # VERBATIM copy of rules.json
+  prd-Employees.usecases.json         # VERBATIM copy of usecases.json
+  prd-Employees.screens.json          # VERBATIM copy of screens.json
+  prd-Employees.permissions.json      # VERBATIM copy of permissions.json
+```
+
+**Validation:**
+```javascript
+const specFiles = prd.specificationFiles;
+if (!specFiles) {
+  BLOCKING_ERROR('specificationFiles missing from PRD');
+}
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+for (const key of specKeys) {
+  if (!specFiles[key]) {
+    BLOCKING_ERROR(`specificationFiles.${key} missing`);
+  }
+  const filePath = path.join('.ralph', specFiles[key]);
+  if (!fs.existsSync(filePath)) {
+    BLOCKING_ERROR(`Companion file not found: ${filePath}`);
+  }
+}
+```
+
+**Why companion files matter:**
+- `/apex` loads only the specs needed per layer (entities for L0, rules+usecases for L2, screens for L3)
+- Context per layer is ~200-500 lines instead of ~2000 lines monolithic
+- Zero risk of specs being lost at the bottom of a large context window
+- Full BA detail available for oneshot generation (attributes, formulas, screen columns)
+
+---
+
 ## Validation Checklist
 
 Use this checklist when validating PRD files:
@@ -219,6 +277,7 @@ Use this checklist when validating PRD files:
 | **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 |
+| **Spec Files** | `specificationFiles` present with 5 paths, all companion files exist | PASS/FAIL |
 
 **All checks must PASS before proceeding to /business-analyse-develop**
 

package/templates/skills/business-analyse-handoff/steps/step-01-transform.md

@@ -151,6 +151,25 @@ Write via ba-writer.enrichModuleHandoff with the complete handoff payload:
 - totalFiles, totalTasks, handedOffAt (ISO timestamp)
 - featureDescription: {featureDescription}
 
+### Specification Files (MANDATORY)
+After writing the handoff data, ALSO write 5 companion files:
+1. `.ralph/prd-{moduleCode}.entities.json` = VERBATIM copy of `{moduleDir}/entities.json`
+2. `.ralph/prd-{moduleCode}.rules.json` = VERBATIM copy of `{moduleDir}/rules.json`
+3. `.ralph/prd-{moduleCode}.usecases.json` = VERBATIM copy of `{moduleDir}/usecases.json`
+4. `.ralph/prd-{moduleCode}.screens.json` = VERBATIM copy of `{moduleDir}/screens.json`
+5. `.ralph/prd-{moduleCode}.permissions.json` = VERBATIM copy of `{moduleDir}/permissions.json`
+
+Add `specificationFiles` to the PRD referencing these files (relative names, all in `.ralph/`):
+```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"
+}
+```
+
 ### POST-CHECK (BLOCKING)
 After writing, verify:
 1. Handoff not empty
@@ -159,7 +178,12 @@ After writing, verify:
 4. Section resources have entity field
 5. SeedData contains CORE entries (NavigationModuleSeedData, NavigationSectionSeedData if sections exist, PermissionsSeedData, RolesSeedData)
 6. For FIRST module only: SeedData contains APP-LEVEL CORE entries (NavigationApplicationSeedData, ApplicationRolesSeedData)
-Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {coreCount} core seeds"
+7. All 5 companion files exist in `.ralph/` and are non-empty
+8. `specificationFiles` present in the PRD with all 5 paths
+9. Entity count in companion matches source: `prd-{moduleCode}.entities.json` entities[] count = `{moduleDir}/entities.json` entities[] count
+10. BR count in companion matches source: `prd-{moduleCode}.rules.json` rules[] count = `{moduleDir}/rules.json` rules[] count
+11. Each `brToCodeMapping[].statement` is non-empty (not just a title paraphrase)
+Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {coreCount} core seeds, 5 companion files"
 ```
 
 ### 3. Display Progress

package/templates/skills/business-analyse-handoff/steps/step-02-export.md

@@ -91,6 +91,26 @@ for (const cat of categories) {
     BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
   }
 }
+
+// Check 5: Specification files (companion files)
+const specFiles = prd.specificationFiles;
+if (!specFiles) {
+  BLOCKING_ERROR("specificationFiles missing from PRD");
+}
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+for (const key of specKeys) {
+  if (!specFiles[key]) {
+    BLOCKING_ERROR(`specificationFiles.${key} path missing`);
+  }
+  const companionPath = `.ralph/${specFiles[key]}`;
+  if (!fileExists(companionPath)) {
+    BLOCKING_ERROR(`Companion file not found: ${companionPath}`);
+  }
+  const companionSize = fileSize(companionPath);
+  if (companionSize < 10) {
+    BLOCKING_ERROR(`Companion file empty or too small: ${companionPath} (${companionSize} bytes)`);
+  }
+}
 ```
 
 Display verification table showing all 8 categories match between module JSON files and prd.json.
@@ -187,10 +207,15 @@ Readiness Scores:
 └──────────────┴────────────┴──────────────┘
 
 Artifacts generated:
-  .ralph/prd-{module}.json      — Task breakdown per module
-  .ralph/progress.txt           — Progression tracker
-  .ralph/modules-queue.json     — Module execution order (if multi-module)
-  docs/index.json               — BA manifest (status: handed-off)
+  .ralph/prd-{module}.json                — Task breakdown per module
+  .ralph/prd-{module}.entities.json       — Entity specifications (companion)
+  .ralph/prd-{module}.rules.json          — Business rules (companion)
+  .ralph/prd-{module}.usecases.json       — Use cases (companion)
+  .ralph/prd-{module}.screens.json        — Screen specifications (companion)
+  .ralph/prd-{module}.permissions.json    — Permissions (companion)
+  .ralph/progress.txt                     — Progression tracker
+  .ralph/modules-queue.json               — Module execution order (if multi-module)
+  docs/index.json                         — BA manifest (status: handed-off)
 
 [NEXT] Development:
   1. Run /business-analyse-develop to begin implementation
@@ -210,5 +235,8 @@ Artifacts generated:
 4. `docs/index.json` updated with correct entry count and status "handed-off"
 5. All PRD files have $version=3.0.0 or 4.0.0, file manifest present, 8 categories
 6. File counts match between PRD and handoff for all categories
+7. For EACH module: 5 companion files exist in `.ralph/` (entities, rules, usecases, screens, permissions)
+8. Each PRD contains `specificationFiles` with all 5 paths
+9. Each companion file is non-empty (>10 bytes)
 
 **IF any check fails -> fix before completing.**