@atlashub/smartstack-cli 4.74.0 → 4.76.0

package/templates/skills/business-analyse-design/steps/step-03-navigation.md

@@ -8,7 +8,7 @@ model: opus
 
 ## Objective
 
-Define the complete navigation tree for the application: routes, menus, breadcrumbs, and seedDataCore entries. This ensures consistent navigation across all modules.
+Define the complete navigation tree for the project: routes, menus, breadcrumbs per application. Supports multi-app projects (uses `applications[]` array).
 
 ## Prerequisites
 
@@ -25,47 +25,56 @@ Read screens.json for every module via ba-reader. Collect all sections and resou
 
 Build the navigation hierarchy following SmartStack conventions:
 
+> **Route depth:** Max 3 segments: `/{app-code}/{module-code}/{section-code}`.
+> Use `:id` for detail sections (e.g., `/rh/employees/:id`).
+> Resources are components WITHIN a page, NOT separate routes.
+
 ```
-Application
-  |-- Module 1
-  |   |-- Section 1 (e.g., "Liste")
-  |   |   |-- Resource 1 (e.g., "employees-grid")
-  |   |-- Section 2 (e.g., "Fiche")
-  |   |   |-- Resource 1 (e.g., "employee-form")
-  |   |-- Section 3 (e.g., "Dashboard")
-  |       |-- Resource 1 (e.g., "hr-dashboard")
-  |-- Module 2
+Project
+  |-- Application 1 (e.g., HumanResources)
+  |   |-- Module 1 (e.g., Employees)
+  |   |   |-- Section "list"   → /rh/employees       (isDefault, showInMenu)
+  |   |   |-- Section "detail" → /rh/employees/:id   (showInMenu: false)
+  |   |   |-- Section "dashboard" → /rh/employees/dashboard (showInMenu)
+  |   |-- Module 2 (e.g., Absences)
+  |-- Application 2 (e.g., Billing)
       |-- ...
 ```
 
 ### 3. Generate navigation.json
 
+> **Multi-app format is MANDATORY.** Even for single-app projects, use `applications[]` (array of 1).
+
 ```json
 {
-  "application": {
-    "code": "{AppCode}",
-    "name": "{AppName}",
-    "icon": "app-icon"
-  },
-  "modules": [
+  "applications": [
     {
-      "code": "{ModuleCode}",
-      "name": "{ModuleName}",
-      "icon": "module-icon",
-      "route": "/{app-code}/{module-code}",
-      "permission": "{AppCode}.{ModuleCode}.Read",
-      "sections": [
+      "code": "{AppCode}",
+      "name": "{AppName}",
+      "icon": "app-icon",
+      "route": "/{app-code}",
+      "modules": [
         {
-          "code": "{sectionCode}",
-          "label": "{sectionLabel}",
-          "route": "/{app-code}/{module-code}/{section-code}",
-          "icon": "section-icon",
-          "resources": [
+          "code": "{ModuleCode}",
+          "name": "{ModuleName}",
+          "icon": "module-icon",
+          "route": "/{app-code}/{module-code}",
+          "permission": "{AppCode}.{ModuleCode}.Read",
+          "sections": [
             {
-              "code": "{resourceCode}",
-              "type": "{SmartTable|SmartForm|SmartDashboard|SmartKanban}",
-              "route": "/{app-code}/{module-code}/{section-code}/{resource-code}",
-              "permission": "{AppCode}.{ModuleCode}.{Action}"
+              "code": "{sectionCode}",
+              "label": "{sectionLabel}",
+              "route": "/{app-code}/{module-code}/{section-code}",
+              "icon": "section-icon",
+              "isDefault": false,
+              "showInMenu": true,
+              "resources": [
+                {
+                  "code": "{resourceCode}",
+                  "type": "{SmartTable|SmartForm|SmartDashboard|SmartKanban|SmartFilter}",
+                  "permission": "{AppCode}.{ModuleCode}.{Action}"
+                }
+              ]
             }
           ]
         }
@@ -74,15 +83,22 @@ Application
   ],
   "menuItems": [
     {
-      "label": "{ModuleName}",
-      "icon": "module-icon",
-      "route": "/{app-code}/{module-code}",
-      "permission": "{AppCode}.{ModuleCode}.Read",
+      "label": "{AppName}",
+      "icon": "app-icon",
+      "route": "/{app-code}",
       "children": [
         {
-          "label": "{sectionLabel}",
-          "route": "/{app-code}/{module-code}/{section-code}",
-          "permission": "{AppCode}.{ModuleCode}.Read"
+          "label": "{ModuleName}",
+          "icon": "module-icon",
+          "route": "/{app-code}/{module-code}",
+          "permission": "{AppCode}.{ModuleCode}.Read",
+          "children": [
+            {
+              "label": "{sectionLabel}",
+              "route": "/{app-code}/{module-code}/{section-code}",
+              "permission": "{AppCode}.{ModuleCode}.Read"
+            }
+          ]
         }
       ]
     }
@@ -97,6 +113,33 @@ Application
 }
 ```
 
+**Section properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isDefault` | boolean | Default section for the module (typically `list`). Only ONE per module. |
+| `showInMenu` | boolean | `true` = visible in sidebar menu, `false` = accessible by navigation only (e.g., detail pages) |
+
+**menuItems rules:**
+
+| Rule | Description |
+|------|-------------|
+| App-level items have NO `permission` | Applications are visible to all authenticated users; permissions gate modules/sections |
+| Single visible section = no `children` | If a module has only ONE section with `showInMenu: true`, render a direct link (no submenu) |
+| Only `showInMenu: true` sections | Detail sections (`showInMenu: false`) are NOT included in menuItems |
+
+**Route conventions:**
+
+| Level | Format | Example |
+|-------|--------|---------|
+| Application | `/{app-code}` | `/rh` |
+| Module | `/{app-code}/{module-code}` | `/rh/employees` |
+| Section (list/default) | `/{app-code}/{module-code}` | `/rh/employees` (isDefault) |
+| Section (named) | `/{app-code}/{module-code}/{section-code}` | `/rh/employees/dashboard` |
+| Section (detail) | `/{app-code}/{module-code}/:id` | `/rh/employees/:id` |
+
+> **Max 3 segments.** Resources are components within a page, NOT separate routes.
+
 ### 4. Write navigation.json
 
 Write via ba-writer at project level: `{docs_dir}/navigation.json` (e.g., `docs/projet-rh/v1.0/navigation.json`).
@@ -105,10 +148,14 @@ Update index.json with navigation.json reference.
 ## Validation
 
 - [ ] Every module in index.json has a corresponding navigation entry
-- [ ] Every section in screens.json has a corresponding menu item
-- [ ] Every route is unique
-- [ ] Every menu item has a valid permission reference
-- [ ] Breadcrumbs cover all routes
+- [ ] Every section with `showInMenu: true` has a corresponding menu item
+- [ ] Every route is unique (no duplicates across all applications)
+- [ ] Module/section-level menu items have valid permission references
+- [ ] App-level menu items have NO permission (visible to all)
+- [ ] Breadcrumbs cover ALL routes (every route in `applications[].modules[].sections[]` must have a breadcrumb entry)
+- [ ] `isDefault: true` is set on exactly ONE section per module
+- [ ] Routes use max 3 segments (+ `:id` for detail)
+- [ ] Single-section modules have no `children` in menuItems
 
 ## Completion Summary
 

package/templates/skills/business-analyse-develop/references/compact-loop.md

@@ -1,5 +1,12 @@
 # Compact Loop — Delegate to /apex
 
++==============================================================================+
+|  COMPACT LOOP — AUTONOMOUS EXECUTION                                         |
+|  This loop runs until ALL tasks complete or dead-end confirmed.             |
+|  EVERY transition in this loop is IMMEDIATE — no pause, no summary,         |
+|  no user interaction. If you stop here = EXECUTION GUARANTEE VIOLATION.     |
++==============================================================================+
+
 > **Loaded by:** step-04 section 5 (after first full iteration)
 > **Purpose:** Execute ALL remaining tasks autonomously by delegating to /apex.
 > **EXECUTION GUARANTEE:** This loop runs until ALL tasks are done, max iterations, or dead-end.
@@ -251,6 +258,8 @@ Apex handles everything for the current module:
 - Commits per layer (atomic commits)
 - Validates with MCP (`validate_conventions`)
 - Updates task statuses in the PRD file directly
+>
+> **MCP HARD RULE:** apex Layer 2 MUST use `mcp__smartstack__scaffold_extension` for controllers/services. Direct Write = BLOCKING violation (step-03c).
 
 > **FLAGS:** `-d` implies `-a` (auto, no user confirmation) and `-e` (economy, no nested teams).
 

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

@@ -0,0 +1,132 @@
+# BA Handoff Quality Gate
+
+> **Used by:** step-01-task.md (section 1b)
+
+## Purpose
+
+Verify that the Business Analysis handoff is complete before generating tasks. A missing or incomplete handoff means no frontend files, no test plan, and no BR-to-code mapping — making full development impossible.
+
+## When This Applies
+
+This quality gate runs **ONLY** when BA artifacts are detected:
+
+```javascript
+const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
+  || findFile('docs/**/business-analyse/**/index.json')
+  || findFile('docs/business/**/business-analyse/**/feature.json');  // legacy fallback
+```
+
+If `sourceFeatureJson` is null (manual start via `{task_description}`, no BA run), **skip this gate intentionally** — the loop proceeds in "manual mode" and generates tasks from the task description. This is by design, not a bug.
+
+---
+
+## Quality Gate Checks
+
+### CHECK 1: Handoff Status
+
+**Purpose:** Verify the BA phase completed and formally handed off.
+
+```javascript
+const feature = readJSON(sourceFeatureJson);
+const handoff = feature.handoff || {};
+
+if (handoff.status !== 'handed-off') {
+  console.error(`BLOCKING: BA HANDOFF INCOMPLETE
+handoff.status = "${handoff.status || 'missing'}" (expected "handed-off")
+Run /business-analyse-handoff to generate the handoff, then re-run /business-analyse-develop.`);
+  STOP;
+}
+```
+
+**Error Message:**
+```
+BLOCKING: BA HANDOFF INCOMPLETE
+handoff.status = "{actual}" (expected "handed-off")
+Run /business-analyse-handoff to generate the handoff, then re-run /business-analyse-develop.
+```
+
+**Status Values:**
+- `"handed-off"` — Handoff complete, safe to proceed
+- `"in-progress"` — BA is still running
+- `"not-started"` — No BA handoff created
+- (missing) — No handoff object at all
+
+---
+
+### CHECK 2: Category Completeness
+
+**Purpose:** Verify all required file categories have entries in filesToCreate.
+
+```javascript
+const filesToCreate = handoff.filesToCreate || {};
+const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);
+
+if (missingInHandoff.length > 0) {
+  console.warn(`⚠ Handoff has empty categories: ${missingInHandoff.join(', ')}`);
+}
+```
+
+**Warning Message:**
+```
+⚠ Handoff has empty categories: {list}
+```
+
+**Impact:** Non-blocking warning. The gate will display which categories are empty but does NOT stop execution. Subsequent checks (e.g., Category Completeness Check in section 4b) may inject guardrails for empty categories.
+
+**Required Categories:**
+1. `domain` — Entity definitions
+2. `application` — Service/handler classes
+3. `infrastructure` — EF configurations, DB migrations
+4. `api` — Controllers, endpoints
+5. `frontend` — Pages, components, screens
+6. `seedData` — Navigation, permissions, roles, seed data
+7. `tests` — Unit and integration tests
+8. `documentation` — API docs, README, architecture docs
+
+---
+
+## Integration with Task Generation
+
+**Before** generating any tasks from filesToCreate, ensure:
+1. Handoff status is `"handed-off"` (CHECK 1)
+2. All required categories are present or empty (CHECK 2, non-blocking)
+
+**After** this gate passes:
+- If filesToCreate exists and has entries → proceed to PRD v3 Transformation (section 2b)
+- If filesToCreate is absent → proceed to task description analysis (section 2)
+
+---
+
+## Manual Mode (No BA Artifacts)
+
+When `sourceFeatureJson` is null, the quality gate is **intentionally skipped**:
+
+```javascript
+if (!sourceFeatureJson) {
+  console.log('Manual mode: no BA artifacts detected — tasks will be generated from task description');
+  // Continue to section 2 (Analyze Task Description)
+}
+```
+
+In manual mode:
+- No handoff status check
+- No filesToCreate validation
+- Task breakdown generated from `{task_description}` (3-30 subtasks)
+- **seedData is still MANDATORY** — generates navigation, permissions, roles
+
+---
+
+## Error Recovery
+
+If CHECK 1 fails (handoff status not "handed-off"):
+
+1. Run `/business-analyse-handoff` to complete BA
+2. Verify `feature.handoff.status === "handed-off"`
+3. Re-run `/business-analyse-develop`
+
+If CHECK 2 warns about empty categories:
+
+1. Review the missing categories
+2. Optionally re-run BA to add files to those categories
+3. Or accept the warning (subsequent guardrails will inject missing categories)

package/templates/skills/business-analyse-develop/references/prd-v3-transformation.md

@@ -0,0 +1,326 @@
+# PRD v3 Transformation: filesToCreate → tasks
+
+> **Used by:** step-01-task.md (section 2b)
+
+## Algorithm: Transform filesToCreate to tasks[]
+
+When PRD v3.0.0 has `implementation.filesToCreate` but NO `tasks[]`, transform all files into a task list with derived acceptance criteria.
+
+### Input
+
+```
+prd.implementation.filesToCreate = {
+  domain: [ { path: "Domain/Employee.cs", ... }, ... ],
+  infrastructure: [ ... ],
+  application: [ ... ],
+  api: [ ... ],
+  seedData: [ ... ],
+  frontend: [ ... ],
+  tests: [ ... ],
+  documentation: [ ... ]
+}
+```
+
+### Companion Specs (Optional)
+
+Load companion specification files to enrich acceptance criteria:
+
+```javascript
+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 */ }
+```
+
+### Transformation Logic
+
+```javascript
+const ftc = prd.implementation.filesToCreate;
+const tasks = [];
+let taskId = 1;
+
+// Category order: domain → infrastructure → application → api → seedData → frontend → tests → documentation
+const categoryOrder = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'tests', 'documentation'];
+
+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);
+```
+
+---
+
+## deriveAcceptanceCriteria() Function
+
+Six category-specific branches derive acceptance criteria from companion specs or fallback to generic statement.
+
+### Category: domain
+
+Extract entity attributes and relationships from `specEntities.entities`:
+
+```javascript
+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;
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: infrastructure
+
+Extract EF configuration from entity spec and attribute names:
+
+```javascript
+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;
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: application
+
+Link to business rules and use cases via `brToCodeMapping` and `linkedUCs`:
+
+```javascript
+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;
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: api
+
+Extract endpoints and permissions from specifications:
+
+```javascript
+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('. ');
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: frontend
+
+Extract screen columns, filters, actions, and KPIs from screen specification:
+
+```javascript
+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;
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: seedData
+
+Extract seed values for business seed data from entity spec:
+
+```javascript
+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;
+}
+```
+
+**Fallback:** `File {path} exists and compiles`
+
+### Category: test / tests
+
+Link to covered business rules and use cases:
+
+```javascript
+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:** `File {path} exists and compiles`
+
+---
+
+## Full Function
+
+```javascript
+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`;
+}
+```