@atlashub/smartstack-cli 3.21.0 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/application/references/application-roles-template.md

@@ -50,7 +50,7 @@ public static class ApplicationRolesSeedData
 {
     // Deterministic GUIDs for application roles
     // Generated from: "role-{applicationId}-{roleType}"
-    private static readonly Guid ApplicationId = {ApplicationGuid}; // From NavigationApplicationSeedData
+    public static readonly Guid ApplicationId = NavigationApplicationSeedData.ApplicationId;
 
     public static readonly Guid AdminRoleId = GenerateRoleGuid("admin");
     public static readonly Guid ManagerRoleId = GenerateRoleGuid("manager");
@@ -141,7 +141,7 @@ public class ApplicationRoleSeedEntry
 |-------------|-------------|---------|
 | `{BaseNamespace}` | Root namespace of the client project | `SmartStack.Modules.RessourcesHumaines` |
 | `{AppLabel}` | Human-readable application label (EN) | `Human Resources` |
-| `{ApplicationGuid}` | GUID of the application (from NavigationApplicationSeedData) | `30f1fbba-e8c3-4879-9a49-d18deaa70a83` |
+| `ApplicationId` | Deterministic GUID from `NavigationApplicationSeedData.ApplicationId` — NO placeholder needed | Auto-resolved |
 
 ---
 

package/templates/skills/application/steps/step-05-frontend.md

@@ -102,7 +102,7 @@ This generates:
 
 > **CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
 
-After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`:
+After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
 
 **Step 4a:** Import the page components at the top of App.tsx:
 
@@ -112,33 +112,49 @@ import { {EntityName}Page } from '@/pages/{Context}/{Application}/{Module}/{Enti
 const {EntityName}Page = lazy(() => import('@/pages/{Context}/{Application}/{Module}/{EntityName}Page'));
 ```
 
-**Step 4b:** Find the correct Layout wrapper block in App.tsx:
+**Step 4b:** Detect the App.tsx routing pattern:
 
-| Context | Layout block to find |
-|---------|---------------------|
-| `platform.*` | `<Route path="/platform" element={<AdminLayout />}>` |
-| `business.*` | `<Route path="/business" element={<BusinessLayout />}>` |
-| `personal.*` | `<Route path="/personal/myspace" element={<UserLayout />}>` |
+Read App.tsx and detect which pattern is used:
 
-**Step 4c:** Insert route entries INSIDE the Layout block (as children, using relative paths):
+**Pattern A** — If App.tsx contains `contextRoutes: ContextRouteExtensions`:
+  → Add routes to `contextRoutes.{context}[]` with **RELATIVE** paths (no leading `/`)
 
-```tsx
-// ✅ CORRECT - Route added INSIDE the layout wrapper
-<Route path="/business" element={<BusinessLayout />}>
-  {/* ... existing routes ... */}
-  <Route path="{application}/{module}" element={<{EntityName}Page />} />
-</Route>
+  ```tsx
+  const contextRoutes: ContextRouteExtensions = {
+    business: [
+      // existing routes...
+      { path: '{application}/{module}/list', element: <{EntityName}ListPage /> },
+      { path: '{application}/{module}/new', element: <Create{EntityName}Page /> },
+      { path: '{application}/{module}/:id', element: <{EntityName}DetailPage /> },
+      { path: '{application}/{module}/:id/edit', element: <Create{EntityName}Page /> },
+    ],
+  };
+  ```
 
-// ❌ FORBIDDEN - Route added OUTSIDE layout (shell will NOT render!)
-<Route path="/business/{application}/{module}" element={<{EntityName}Page />} />
-```
+  Routes are automatically injected into BOTH standard (`/business/...`) and tenant-prefixed (`/t/:slug/business/...`) route trees by `mergeRoutes()`. No manual duplication needed.
+
+**Pattern B** — If App.tsx contains `<Route path="/{context}" element={<{Layout} />}>` (JSX Routes):
+  → Insert `<Route>` children inside the Layout wrapper (see below)
 
-**Step 4d:** ALSO add the same routes inside the tenant-prefixed block:
+  ```tsx
+  <Route path="/business" element={<BusinessLayout />}>
+    {/* ... existing routes ... */}
+    <Route path="{application}/{module}" element={<{EntityName}Page />} />
+  </Route>
+  ```
 
-Find `<Route path="/t/:slug">` and locate the matching `<Route path="{context}" element={<{Layout} />}>` inside it.
-Add the **same route entries** there.
+  ALSO add the same routes inside the tenant-prefixed block:
+  Find `<Route path="/t/:slug">` and add the **same route entries** there.
 
-**Step 4e:** Verify wiring:
+**Step 4c:** Context-to-Layout mapping:
+
+| Context | Layout Component | Route path |
+|---------|------------------|------------|
+| `platform.*` | `AdminLayout` | `/platform` |
+| `business.*` | `BusinessLayout` | `/business` |
+| `personal.*` | `UserLayout` | `/personal/myspace` |
+
+**Step 4d:** Verify wiring:
 
 ```
 Tool: mcp__smartstack__validate_frontend_routes
@@ -148,21 +164,10 @@ Args:
 
 If `appWiring.issues` is not empty, fix the wiring before proceeding.
 
-**For new applications (no existing layout route for the context):**
-
-If the context doesn't have a layout route yet, create one wrapping all child routes:
-
-```tsx
-<Route path="/{context}/{application}" element={<{Context}Layout />}>
-  <Route index element={<Navigate to="{default_module}" replace />} />
-  <Route path="{module}" element={<{EntityName}Page />} />
-</Route>
-```
-
-**FORBIDDEN:**
+**FORBIDDEN (both patterns):**
+- Adding business/platform/personal routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack contexts (e.g., `/about`, `/pricing`)
 - Adding routes OUTSIDE the Layout wrapper (shell will not render)
-- Adding routes only in the standard block but not in the tenant block
-- Using `createBrowserRouter` (SmartStack uses `BrowserRouter` with JSX `<Routes>`)
+- Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
 
 ### 5. Verify i18n Files
 

package/templates/skills/application/templates-frontend.md

@@ -488,7 +488,51 @@ export const $moduleApi = {
 
 ## TEMPLATE: ROUTES (App.tsx)
 
-### ⚠️ CRITICAL RULE 1: ROUTES MUST BE INSIDE LAYOUT WRAPPER
+### Detect App.tsx Routing Pattern FIRST
+
+Before adding routes, **read App.tsx** and detect which pattern is used:
+
+| Pattern | How to detect | Action |
+|---------|---------------|--------|
+| **Pattern A** (mergeRoutes) | `contextRoutes: ContextRouteExtensions` present | Add to `contextRoutes.{context}[]` array |
+| **Pattern B** (JSX Routes) | `<Route path="/{context}" element={<{Layout} />}>` present | Insert `<Route>` children inside Layout wrapper |
+
+### Pattern A: mergeRoutes (contextRoutes array)
+
+> **This is the DEFAULT pattern** generated by `smartstack init`.
+> Routes added to `contextRoutes` are automatically injected into BOTH standard and tenant-prefixed route trees by `mergeRoutes()`. No manual duplication needed.
+
+```tsx
+// Add to App.tsx — imports at top
+import { $MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/$MODULE_PASCALPage';
+import { $MODULE_PASCALDetailPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/$MODULE_PASCALDetailPage';
+import { Create$MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/Create$MODULE_PASCALPage';
+
+// Add routes to contextRoutes.{context}[] with RELATIVE paths (no leading /)
+const contextRoutes: ContextRouteExtensions = {
+  $CONTEXT: [
+    // ... existing routes ...
+    { path: '$APPLICATION/$MODULE', element: <$MODULE_PASCALPage /> },
+    { path: '$APPLICATION/$MODULE/new', element: <Create$MODULE_PASCALPage /> },
+    { path: '$APPLICATION/$MODULE/:id', element: <$MODULE_PASCALDetailPage /> },
+    { path: '$APPLICATION/$MODULE/:id/edit', element: <Create$MODULE_PASCALPage /> },
+  ],
+};
+```
+
+**mergeRoutes auto-generates redirects** for intermediate paths (e.g., `$APPLICATION` → `$APPLICATION/$DEFAULT_MODULE`) so you don't need to add index redirects manually.
+
+**Context-to-Layout mapping (automatic via mergeRoutes):**
+
+| Context key | Injected into Layout | Standard path | Tenant path |
+|-------------|---------------------|---------------|-------------|
+| `platform` | `AdminLayout` | `/platform/...` | `/t/:slug/platform/...` |
+| `business` | `BusinessLayout` | `/business/...` | `/t/:slug/business/...` |
+| `personal` | `UserLayout` | `/personal/myspace/...` | `/t/:slug/personal/myspace/...` |
+
+### Pattern B: JSX Routes (inside Layout wrapper)
+
+> **Legacy pattern** — only used if App.tsx was manually restructured with JSX `<Route>` elements.
 
 SmartStack layouts (`AdminLayout`, `BusinessLayout`, `UserLayout`) provide the application shell: **header with AvatarMenu**, sidebar, navigation. They render child pages via React Router's `<Outlet />`.
 
@@ -504,13 +548,6 @@ SmartStack layouts (`AdminLayout`, `BusinessLayout`, `UserLayout`) provide the a
 3. Add the new routes **INSIDE** that `<Route>` block
 4. If a tenant-prefixed block exists (`/t/:slug/...`), add the routes there too
 
-**❌ FORBIDDEN - Flat routes OUTSIDE layout (AvatarMenu disappears!)**
-```tsx
-// These routes bypass the layout system entirely = NO header, NO sidebar, NO AvatarMenu
-<Route path="/$CONTEXT/$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
-```
-
-**✅ MANDATORY - Routes INSIDE the existing layout wrapper**
 ```tsx
 // Add to App.tsx
 
@@ -533,42 +570,33 @@ import { Create$MODULE_PASCALPage } from '@/pages/$CONTEXT/$APPLICATION/$MODULE/
 </Route>
 ```
 
-### Context-to-Layout mapping
+### ⚠️ CRITICAL RULES (both patterns)
 
-| Context | Layout Component | Layout Route Path |
-|---------|------------------|-------------------|
-| `platform` | `AdminLayout` | `/platform` |
-| `business` | `BusinessLayout` | `/business` |
-| `personal` | `UserLayout` | `/personal/myspace` |
-
-### ⚠️ CRITICAL RULE 2: NESTED ROUTES MANDATORY
-
-React Router v7 **requires** nested routes for multi-module applications.
-
-**❌ FORBIDDEN - Flat routes (cause redirects to Home)**
+**FORBIDDEN — Adding to clientRoutes[] with absolute paths:**
 ```tsx
-<Route path="$APPLICATION" element={<Navigate to="/$CONTEXT/$APPLICATION/$DEFAULT_MODULE" replace />} />
-<Route path="$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
+// ❌ WRONG — bypasses layout entirely, shell will NOT render
+const clientRoutes: RouteConfig[] = [
+  { path: '/business/$APPLICATION/$MODULE', element: <$MODULE_PASCALPage /> },
+];
 ```
 
-**✅ MANDATORY - Nested routes with index**
+`clientRoutes` is ONLY for routes **outside** SmartStack locked contexts (e.g., `/about`, `/pricing`).
+
+**FORBIDDEN — Flat routes outside layout:**
 ```tsx
-<Route path="$APPLICATION">
-  <Route index element={<Navigate to="$DEFAULT_MODULE" replace />} />
-  <Route path="$MODULE" element={<$MODULE_PASCALPage />} />
-</Route>
+// ❌ WRONG (Pattern B only) — flat route bypasses layout
+<Route path="/$CONTEXT/$APPLICATION/$MODULE" element={<$MODULE_PASCALPage />} />
 ```
 
-### Why this structure?
+### Why nested/context routes?
 
-| Aspect | Flat routes | Nested routes |
-|--------|------------|----------------|
-| Shell rendered | ❌ No (bypasses layout) | ✅ Yes (Outlet pattern) |
-| AvatarMenu visible | ❌ No | ✅ Yes |
-| Matching | Ambiguous between siblings | Hierarchical clear |
-| Navigate | Must be absolute | Can be relative |
-| Outlet | Not supported | Supported |
-| Redirect | Can fail | Always works |
+| Aspect | clientRoutes (wrong) | contextRoutes / nested (correct) |
+|--------|---------------------|----------------------------------|
+| Shell rendered | No (bypasses layout) | Yes (Outlet pattern) |
+| AvatarMenu visible | No | Yes |
+| Tenant prefix | Manual duplication | Automatic (mergeRoutes) |
+| Auto-redirects | None | Generated for intermediate paths |
+| Permission check | Bypassed (no RouteGuard) | Enforced by RouteGuard |
 
 ---
 

package/templates/skills/business-analyse/html/ba-interactive.html

@@ -993,6 +993,48 @@ body {
 .svg-wireframe svg {
     max-width: 100%;
     height: auto;
+    display: block;
+}
+
+/* ============================================
+   WIREFRAME VIEW TOGGLE (SVG / ASCII)
+   ============================================ */
+.wireframe-toggle {
+    display: flex;
+    gap: 2px;
+    background: var(--bg-dark);
+    border-radius: 6px;
+    padding: 2px;
+    border: 1px solid var(--border);
+    margin-left: auto;
+}
+
+.wireframe-toggle-btn {
+    padding: 0.25rem 0.6rem;
+    font-size: 0.7rem;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    background: transparent;
+    color: var(--text-muted);
+    transition: all 0.15s ease;
+    font-family: inherit;
+}
+
+.wireframe-toggle-btn:hover {
+    color: var(--text-bright);
+    background: var(--bg-hover);
+}
+
+.wireframe-toggle-btn.active {
+    background: var(--primary);
+    color: #ffffff;
+}
+
+.wireframe-view:not(.active) {
+    display: none;
 }
 
 .wireframe-description {
@@ -3279,18 +3321,30 @@ function renderModuleMockups(code) {
             </div>`;
     }
 
-    return wireframes.map((wf, i) => `
+    return wireframes.map((wf, i) => {
+        const hasSvg = !!wf.svgContent;
+        const wireframeId = `wf-${code}-${i}`;
+
+        return `
         <div class="mockup-frame" style="${i > 0 ? 'margin-top:1.5rem;' : ''}">
             <div class="mockup-toolbar">
                 <div class="mockup-dot mockup-dot-red"></div>
                 <div class="mockup-dot mockup-dot-yellow"></div>
                 <div class="mockup-dot mockup-dot-green"></div>
                 <span class="mockup-title">${wf.screen || wf.section}</span>
+                ${hasSvg ? `
+                <div class="wireframe-toggle">
+                    <button class="wireframe-toggle-btn active" data-target="${wireframeId}" data-view="svg" onclick="toggleWireframeView('${wireframeId}', 'svg')">SVG</button>
+                    <button class="wireframe-toggle-btn" data-target="${wireframeId}" data-view="ascii" onclick="toggleWireframeView('${wireframeId}', 'ascii')">ASCII</button>
+                </div>` : ''}
             </div>
-            <div class="mockup-content">
-                ${wf.format === 'ascii'
-                    ? `<pre class="ascii-wireframe">${wf.content || ''}</pre>`
-                    : `<div class="svg-wireframe">${wf.content || ''}</div>`}
+            <div class="mockup-content" id="${wireframeId}">
+                ${hasSvg
+                    ? `<div class="svg-wireframe wireframe-view active" data-view="svg">${wf.svgContent}</div>
+                       <pre class="ascii-wireframe wireframe-view" data-view="ascii" style="display:none;">${wf.content || ''}</pre>`
+                    : (wf.format === 'ascii'
+                        ? `<pre class="ascii-wireframe">${wf.content || ''}</pre>`
+                        : `<div class="svg-wireframe">${wf.content || ''}</div>`)}
             </div>
             ${wf.description ? `
             <div class="wireframe-description">
@@ -3329,7 +3383,27 @@ function renderModuleMockups(code) {
                 >${getWireframeComment(code, wf.screen)}</textarea>
             </div>
         </div>
-    `).join('');
+    `}).join('');
+}
+
+function toggleWireframeView(wireframeId, view) {
+    const container = document.getElementById(wireframeId);
+    if (!container) return;
+
+    // Toggle visibility of wireframe views
+    container.querySelectorAll('.wireframe-view').forEach(el => {
+        const isTarget = el.dataset.view === view;
+        el.style.display = isTarget ? '' : 'none';
+        el.classList.toggle('active', isTarget);
+    });
+
+    // Toggle button active states
+    const toolbar = container.closest('.mockup-frame').querySelector('.wireframe-toggle');
+    if (toolbar) {
+        toolbar.querySelectorAll('.wireframe-toggle-btn').forEach(btn => {
+            btn.classList.toggle('active', btn.dataset.view === view);
+        });
+    }
 }
 
 function getPermRoles() {

package/templates/skills/business-analyse/html/src/scripts/05-render-specs.js

@@ -387,18 +387,30 @@ function renderModuleMockups(code) {
             </div>`;
     }
 
-    return wireframes.map((wf, i) => `
+    return wireframes.map((wf, i) => {
+        const hasSvg = !!wf.svgContent;
+        const wireframeId = `wf-${code}-${i}`;
+
+        return `
         <div class="mockup-frame" style="${i > 0 ? 'margin-top:1.5rem;' : ''}">
             <div class="mockup-toolbar">
                 <div class="mockup-dot mockup-dot-red"></div>
                 <div class="mockup-dot mockup-dot-yellow"></div>
                 <div class="mockup-dot mockup-dot-green"></div>
                 <span class="mockup-title">${wf.screen || wf.section}</span>
+                ${hasSvg ? `
+                <div class="wireframe-toggle">
+                    <button class="wireframe-toggle-btn active" data-target="${wireframeId}" data-view="svg" onclick="toggleWireframeView('${wireframeId}', 'svg')">SVG</button>
+                    <button class="wireframe-toggle-btn" data-target="${wireframeId}" data-view="ascii" onclick="toggleWireframeView('${wireframeId}', 'ascii')">ASCII</button>
+                </div>` : ''}
             </div>
-            <div class="mockup-content">
-                ${wf.format === 'ascii'
-                    ? `<pre class="ascii-wireframe">${wf.content || ''}</pre>`
-                    : `<div class="svg-wireframe">${wf.content || ''}</div>`}
+            <div class="mockup-content" id="${wireframeId}">
+                ${hasSvg
+                    ? `<div class="svg-wireframe wireframe-view active" data-view="svg">${wf.svgContent}</div>
+                       <pre class="ascii-wireframe wireframe-view" data-view="ascii" style="display:none;">${wf.content || ''}</pre>`
+                    : (wf.format === 'ascii'
+                        ? `<pre class="ascii-wireframe">${wf.content || ''}</pre>`
+                        : `<div class="svg-wireframe">${wf.content || ''}</div>`)}
             </div>
             ${wf.description ? `
             <div class="wireframe-description">
@@ -437,7 +449,27 @@ function renderModuleMockups(code) {
                 >${getWireframeComment(code, wf.screen)}</textarea>
             </div>
         </div>
-    `).join('');
+    `}).join('');
+}
+
+function toggleWireframeView(wireframeId, view) {
+    const container = document.getElementById(wireframeId);
+    if (!container) return;
+
+    // Toggle visibility of wireframe views
+    container.querySelectorAll('.wireframe-view').forEach(el => {
+        const isTarget = el.dataset.view === view;
+        el.style.display = isTarget ? '' : 'none';
+        el.classList.toggle('active', isTarget);
+    });
+
+    // Toggle button active states
+    const toolbar = container.closest('.mockup-frame').querySelector('.wireframe-toggle');
+    if (toolbar) {
+        toolbar.querySelectorAll('.wireframe-toggle-btn').forEach(btn => {
+            btn.classList.toggle('active', btn.dataset.view === view);
+        });
+    }
 }
 
 function getPermRoles() {

package/templates/skills/business-analyse/html/src/styles/06-wireframes.css

@@ -61,6 +61,48 @@
 .svg-wireframe svg {
     max-width: 100%;
     height: auto;
+    display: block;
+}
+
+/* ============================================
+   WIREFRAME VIEW TOGGLE (SVG / ASCII)
+   ============================================ */
+.wireframe-toggle {
+    display: flex;
+    gap: 2px;
+    background: var(--bg-dark);
+    border-radius: 6px;
+    padding: 2px;
+    border: 1px solid var(--border);
+    margin-left: auto;
+}
+
+.wireframe-toggle-btn {
+    padding: 0.25rem 0.6rem;
+    font-size: 0.7rem;
+    font-weight: 500;
+    letter-spacing: 0.02em;
+    border: none;
+    border-radius: 4px;
+    cursor: pointer;
+    background: transparent;
+    color: var(--text-muted);
+    transition: all 0.15s ease;
+    font-family: inherit;
+}
+
+.wireframe-toggle-btn:hover {
+    color: var(--text-bright);
+    background: var(--bg-hover);
+}
+
+.wireframe-toggle-btn.active {
+    background: var(--primary);
+    color: #ffffff;
+}
+
+.wireframe-view:not(.active) {
+    display: none;
 }
 
 .wireframe-description {

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

@@ -0,0 +1,169 @@
+# Module Acceptance Criteria (Shared Reference)
+
+> **Loaded by:** step-03d-validate (section 11-POST-CHECK-BASH), step-05a-handoff (pre-handoff gate), ralph-loop step-01-task (input validation)
+> **Purpose:** Define measurable, bash-verifiable acceptance criteria that a module MUST pass before being marked "specified".
+> **Key principle:** These checks read the REAL feature.json file on disk — NOT in-memory data the model "thinks" it wrote.
+
+---
+
+## Why Bash-Verifiable?
+
+All previous checks were **pseudocode interpreted by the model**. The model can "decide" a check passes even when it fails (hallucination of validation). Bash checks are **objective** — they read the actual file and count real elements.
+
+---
+
+## Acceptance Criteria Table
+
+| # | Criterion | Minimum | Field Path | Blocking | Category |
+|---|-----------|---------|------------|----------|----------|
+| AC-01 | Entities present | 1 | `analysis.entities[]` | YES | Data Model |
+| AC-02 | Entity attributes have `type` field | ALL | `analysis.entities[].attributes[].type` | YES | Data Model |
+| AC-03 | Use cases present | 2 | `specification.useCases[]` | YES | Requirements |
+| AC-04 | Functional requirements present | 4 | `specification.functionalRequirements[]` | YES | Requirements |
+| AC-05 | Wireframes present | 1 | `specification.uiWireframes[] \|\| specification.wireframes[]` | YES | UI |
+| AC-06 | Wireframes >= sections | count match | wireframes.length >= sections.length | YES | UI |
+| AC-07 | Wireframe content non-empty | ALL | `wireframe.mockup \|\| wireframe.ascii \|\| wireframe.content` | YES | UI |
+| AC-08 | Sections present | 1 | `specification.sections[]` | YES | UI |
+| AC-09 | SeedDataCore 7 arrays non-empty | 7/7 | `specification.seedDataCore.*` | YES | Seed Data |
+| AC-10 | Gherkin scenarios is array | `Array.isArray` | `specification.gherkinScenarios` | YES | Format |
+| AC-11 | API endpoints present | 1 | `specification.apiEndpoints[]` | YES | API |
+| AC-12 | Messages present | 4 | `specification.messages[]` | YES | Messages |
+| AC-13 | Validations present | 1 | `specification.validations[]` | YES | Validation |
+| AC-14 | Wireframe field naming | canonical | `screen` not `title`, `mockup` not `ascii` | WARNING | Convention |
+| AC-15 | Validation rules format | ALL array | `specification.validations[].rules` is `Array` | YES | Format |
+| AC-16 | Messages have `message` field | ALL present | `specification.messages[].message` truthy | YES | Format |
+| AC-17 | Gherkin content structure | ALL valid | Each element has `feature` (string) + `scenarios` (array) | YES | Format |
+
+---
+
+## Bash Verification Script (node -e)
+
+> **Usage:** Called from step-03d section 11-POST-CHECK-BASH after writing module feature.json.
+> Also callable standalone for debugging: `node -e "..." path/to/feature.json`
+
+```bash
+MODULE_JSON="{module_feature_json_path}"
+node -e "
+const fs = require('fs');
+const data = JSON.parse(fs.readFileSync(process.argv[1], 'utf-8'));
+const spec = data.specification || {};
+const analysis = data.analysis || {};
+const wf = spec.uiWireframes || spec.wireframes || [];
+const sections = spec.sections || [];
+const sdc = spec.seedDataCore || {};
+
+const checks = [
+  ['AC-01: entities >= 1',          (analysis.entities||[]).length,               1],
+  ['AC-03: useCases >= 2',          (spec.useCases||[]).length,                   2],
+  ['AC-04: FRs >= 4',               (spec.functionalRequirements||[]).length,     4],
+  ['AC-05: wireframes >= 1',        wf.length,                                    1],
+  ['AC-06: wireframes >= sections', wf.length,                                    sections.length],
+  ['AC-08: sections >= 1',          sections.length,                               1],
+  ['AC-09: seedDataCore 7 arrays',  Object.keys(sdc).filter(k => Array.isArray(sdc[k]) && sdc[k].length > 0).length, 7],
+  ['AC-10: gherkin is array',       Array.isArray(spec.gherkinScenarios) ? 1 : 0,  1],
+  ['AC-11: apiEndpoints >= 1',      (spec.apiEndpoints||[]).length,                1],
+  ['AC-12: messages >= 4',          (spec.messages||[]).length,                    4],
+  ['AC-13: validations >= 1',       (spec.validations||[]).length,                 1]
+];
+
+const fails = [];
+checks.forEach(c => {
+  if (c[1] < c[2]) {
+    fails.push(c);
+    console.error('FAIL: ' + c[0] + ' = ' + c[1] + ' (min: ' + c[2] + ')');
+  }
+});
+
+// AC-02: Entity attribute types
+const badAttrs = (analysis.entities||[]).flatMap(e =>
+  (e.attributes||[]).filter(a => !a.type).map(a => e.name + '.' + a.name)
+);
+if (badAttrs.length > 0) {
+  fails.push(['AC-02: attr.type missing', badAttrs.length, 0]);
+  console.error('FAIL: AC-02: ' + badAttrs.length + ' attributes without type: ' + badAttrs.slice(0, 5).join(', ') + (badAttrs.length > 5 ? '...' : ''));
+}
+
+// AC-07: Wireframe content non-empty
+const emptyWf = wf.filter(w => !w.mockup && !w.ascii && !w.content);
+if (emptyWf.length > 0) {
+  fails.push(['AC-07: wireframe content empty', emptyWf.length, 0]);
+  console.error('FAIL: AC-07: ' + emptyWf.length + ' wireframes have EMPTY content');
+}
+
+// AC-14: Wireframe field naming (WARNING only)
+const badFields = wf.filter(w => w.title || w.ascii || (w.name && !w.screen));
+if (badFields.length > 0) {
+  console.warn('WARNING: AC-14: ' + badFields.length + ' wireframes use non-canonical field names (title/ascii/name)');
+}
+
+// AC-15: Validation rules format (rules must be array, not string)
+const badRules = (spec.validations||[]).filter(v => v.rules && !Array.isArray(v.rules));
+if (badRules.length > 0) {
+  fails.push(['AC-15: validations[].rules not array', badRules.length, 0]);
+  console.error('FAIL: AC-15: ' + badRules.length + ' validations have rules as string instead of array');
+}
+
+// AC-16: Messages must have 'message' field
+const noMsg = (spec.messages||[]).filter(m => !m.message);
+if (noMsg.length > 0) {
+  fails.push(['AC-16: messages[].message missing', noMsg.length, 0]);
+  console.error('FAIL: AC-16: ' + noMsg.length + ' messages missing "message" field');
+}
+
+// AC-17: Gherkin content structure (each element needs feature + scenarios[])
+if (Array.isArray(spec.gherkinScenarios)) {
+  const badGherkin = spec.gherkinScenarios.filter(g => !g.feature || !Array.isArray(g.scenarios));
+  if (badGherkin.length > 0) {
+    fails.push(['AC-17: gherkin content invalid', badGherkin.length, 0]);
+    console.error('FAIL: AC-17: ' + badGherkin.length + ' gherkin entries missing feature or scenarios[]');
+  }
+}
+
+// Summary
+if (fails.length > 0) {
+  console.error('\\nBLOCKING: ' + fails.length + ' acceptance criteria FAILED');
+  process.exit(1);
+}
+console.log('PASS: All acceptance criteria met (AC-01 to AC-17)');
+" "$MODULE_JSON"
+```
+
+---
+
+## Integration Points
+
+### 1. step-03d-validate.md (section 11-POST-CHECK-BASH)
+
+After writing module feature.json, run the bash script above.
+IF FAIL → re-execute section 11 write with corrected data → re-run until PASS.
+
+### 2. step-05a-handoff.md (pre-handoff gate)
+
+Before writing handoff for each module (section 7a step 3), run the bash script on the module feature.json.
+IF FAIL → STOP handoff for this module, report which criteria failed.
+
+### 3. ralph-loop step-01-task.md (input validation)
+
+At PRD load time, run the bash script on each module feature.json.
+IF FAIL → BLOCKING: "Module {name} does not meet acceptance criteria — run /business-analyse to fix".
+This prevents ralph-loop from generating code from incomplete specifications.
+
+---
+
+## Recovery Actions per Criterion
+
+| Criterion | Recovery |
+|-----------|----------|
+| AC-01/02 | Re-run step-03a2-analysis (entity definition) |
+| AC-03/04 | Re-run step-03c-compile sections 8b/8c |
+| AC-05/06/07 | Re-run step-03b-ui (wireframe generation) — step-03b now writes intermediately |
+| AC-08 | Re-run step-03b section 3a-bis (section definition) |
+| AC-09 | Re-run step-03c section 8f-bis (seedDataCore transform) |
+| AC-10 | Auto-fix: wrap in array `[gherkinScenarios]` |
+| AC-11 | Re-run step-03c section 8k |
+| AC-12 | Re-run step-03c section 8i |
+| AC-13 | Re-run step-03c section 8h |
+| AC-14 | Auto-fix: rename title→screen, ascii→mockup (done by step-03c/03d auto-fix) |
+| AC-15 | Auto-fix: wrap string in array `[rules]` (done by step-03c ABSOLUTE FORMAT CHECKS) |
+| AC-16 | Auto-fix: copy `description` → `message` (done by step-03c ABSOLUTE FORMAT CHECKS) |
+| AC-17 | Re-run step-03c section 8g — ensure each gherkin entry has `feature` string + `scenarios` array |