@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/business-analyse/references/deploy-modes.md

@@ -1,118 +1,118 @@
-# Deploy Mode Support & Troubleshooting
-
-> Reference for step-05b-deploy.md — mode variations and common issues.
-
-## Mode Support
-
-### Standard Mode
-
-Full handoff with all implementation details:
-- All 7 file categories
-- Complete BR-to-code mapping
-- Full API endpoint summary
-- Detailed prd.json
-- Comprehensive progress tracker
-
-### Micro Mode (use_case = micro)
-
-Simplified handoff with minimal scope:
-- Only essential CRUD entity + controller
-- 3 core SeedData entries (omit some optional ones)
-- Basic prd.json with simplified sections
-- Lightweight progress.txt
-- Display `/ralph-loop` command for later use
-
-### Delta Mode (use_case = refactoring)
-
-Focused handoff for changes:
-- Only affected modules listed
-- Reuse existing implementation patterns
-- Highlight what changed vs baseline
-- Update only affected prd.json sections
-- Progress tracker shows only delta tasks
-
-### Multi-Application Mode (workflow.mode = "project")
-
-Full handoff across multiple applications within a project:
-
-**Artifacts generated:**
-- Per-module: `.ralph/prd-{moduleCode}.json` (one per module across all applications)
-- Per-application cross-module: `.ralph/prd-CrossModule-{appCode}.json` (if app has 2+ modules)
-- Cross-application: `.ralph/prd-CrossApplication.json` (integration tests between applications)
-- Progress tracker: `.ralph/progress.txt` (grouped by application, then by module)
-- BA manifest: `docs/index.json` (project-level entry + per-application + per-module entries)
-- Interactive HTML: one HTML file per application at `docs/{app}/business-analyse/v{version}/ba-interactive.html`
-
-**Project-level manifest entry:**
-```json
-{
-  "scope": "project",
-  "projectId": "PROJ-001",
-  "projectName": "HR Platform",
-  "version": "1.0",
-  "status": "handed-off",
-  "applications": ["HumanResources", "EmployeeSelfService"],
-  "path": "business-analyse/v1.0/feature.json",
-  "updatedAt": "2026-02-16T..."
-}
-```
-
-**Progress tracker structure (multi-app):**
-```
-# Progress Tracker — {projectName}
-
-## Application: {app1Name} ({app1Context})
-
-### Module: {module1} (Layer 0 — simple)
-- [ ] Domain: Entity1.cs
-- [ ] Application: Entity1Service.cs
-...
-
-### Module: {module2} (Layer 1 — medium)
-...
-
-## Application: {app2Name} ({app2Context})
-...
-
-## Cross-Application Integration
-- [ ] SharedEntityValidationTests.cs
-- [ ] CrossAppPermissionTests.cs
-- [ ] CrossAppE2EFlowTests.cs
-
-## Summary
-| Application | Modules | Files | Tasks | Complexity |
-|-------------|---------|-------|-------|------------|
-| {app1}      | {n}     | {n}   | {n}   | {level}    |
-| {app2}      | {n}     | {n}   | {n}   | {level}    |
-| Cross-App   | —       | 3     | 3     | —          |
-| **Total**   | {n}     | {n}   | {n}   | {global}   |
-```
-
-**seedDataCore differences:**
-- `navigationApplications[]` has one entry per application
-- `navigationModules[]` includes `applicationCode` field for each module
-- `permissions[]` use per-application prefixes (e.g., `hr.*` vs `admin.*`)
-- `rolePermissions[]` are scoped per application (same role can have different permissions per app)
-- Seed data order: applications in topological order, then modules within each application
-
-**ralph-loop execution (recommended):**
-- Run `/ralph-loop` once per application (module-by-module within each app)
-- Cross-application PRD runs last after all applications are implemented
-- Application order follows `applicationDependencyGraph.topologicalOrder`
-
-## Troubleshooting
-
-| Issue | Resolution |
-|-------|-----------|
-| All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
-| prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
-| progress.txt incomplete | Ensure all CORE SeedData entries are present: 2 app-level (NavigationApplication + ApplicationRoles) + per module (NavigationModule + NavigationSections + Permissions + Roles). Check topological order. |
-| BA manifest not found | Create docs/index.json if missing. Use schema provided in section 3. |
-| Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.json metadata exactly. |
-| ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
-| moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
-| Scope keys still show "mustHave" instead of "vital" | Conversion from feature.json keys to HTML keys failed. Check cadrage.scope conversion logic. |
-| Wireframes array is empty | Verify each module has specification.uiWireframes. If missing, add wireframe stubs. |
-| dependencyGraph missing | Verify master feature.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
-| HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
-| Export/re-import fails | Verify exported JSON matches original feature.json schema. Validate with `/business-analyse -x --validate`. |
+# Deploy Mode Support & Troubleshooting
+
+> Reference for step-05b-deploy.md — mode variations and common issues.
+
+## Mode Support
+
+### Standard Mode
+
+Full handoff with all implementation details:
+- All 7 file categories
+- Complete BR-to-code mapping
+- Full API endpoint summary
+- Detailed prd.json
+- Comprehensive progress tracker
+
+### Micro Mode (use_case = micro)
+
+Simplified handoff with minimal scope:
+- Only essential CRUD entity + controller
+- 3 core SeedData entries (omit some optional ones)
+- Basic prd.json with simplified sections
+- Lightweight progress.txt
+- Display `/ralph-loop` command for later use
+
+### Delta Mode (use_case = refactoring)
+
+Focused handoff for changes:
+- Only affected modules listed
+- Reuse existing implementation patterns
+- Highlight what changed vs baseline
+- Update only affected prd.json sections
+- Progress tracker shows only delta tasks
+
+### Multi-Application Mode (workflow.mode = "project")
+
+Full handoff across multiple applications within a project:
+
+**Artifacts generated:**
+- Per-module: `.ralph/prd-{moduleCode}.json` (one per module across all applications)
+- Per-application cross-module: `.ralph/prd-CrossModule-{appCode}.json` (if app has 2+ modules)
+- Cross-application: `.ralph/prd-CrossApplication.json` (integration tests between applications)
+- Progress tracker: `.ralph/progress.txt` (grouped by application, then by module)
+- BA manifest: `docs/index.json` (project-level entry + per-application + per-module entries)
+- Interactive HTML: one HTML file per application at `docs/{app}/business-analyse/v{version}/ba-interactive.html`
+
+**Project-level manifest entry:**
+```json
+{
+  "scope": "project",
+  "projectId": "PROJ-001",
+  "projectName": "HR Platform",
+  "version": "1.0",
+  "status": "handed-off",
+  "applications": ["HumanResources", "EmployeeSelfService"],
+  "path": "business-analyse/v1.0/feature.json",
+  "updatedAt": "2026-02-16T..."
+}
+```
+
+**Progress tracker structure (multi-app):**
+```
+# Progress Tracker — {projectName}
+
+## Application: {app1Name} ({app1Context})
+
+### Module: {module1} (Layer 0 — simple)
+- [ ] Domain: Entity1.cs
+- [ ] Application: Entity1Service.cs
+...
+
+### Module: {module2} (Layer 1 — medium)
+...
+
+## Application: {app2Name} ({app2Context})
+...
+
+## Cross-Application Integration
+- [ ] SharedEntityValidationTests.cs
+- [ ] CrossAppPermissionTests.cs
+- [ ] CrossAppE2EFlowTests.cs
+
+## Summary
+| Application | Modules | Files | Tasks | Complexity |
+|-------------|---------|-------|-------|------------|
+| {app1}      | {n}     | {n}   | {n}   | {level}    |
+| {app2}      | {n}     | {n}   | {n}   | {level}    |
+| Cross-App   | —       | 3     | 3     | —          |
+| **Total**   | {n}     | {n}   | {n}   | {global}   |
+```
+
+**seedDataCore differences:**
+- `navigationApplications[]` has one entry per application
+- `navigationModules[]` includes `applicationCode` field for each module
+- `permissions[]` use per-application prefixes (e.g., `hr.*` vs `admin.*`)
+- `rolePermissions[]` are scoped per application (same role can have different permissions per app)
+- Seed data order: applications in topological order, then modules within each application
+
+**ralph-loop execution (recommended):**
+- Run `/ralph-loop` once per application (module-by-module within each app)
+- Cross-application PRD runs last after all applications are implemented
+- Application order follows `applicationDependencyGraph.topologicalOrder`
+
+## Troubleshooting
+
+| Issue | Resolution |
+|-------|-----------|
+| All modules missing handoff data | Return to step-05a-handoff.md. Handoff MUST be written to each module feature.json. |
+| prd.json generation failed | Verify ss derive-prd command is installed and feature.json path is correct. |
+| progress.txt incomplete | Ensure all CORE SeedData entries are present: 2 app-level (NavigationApplication + ApplicationRoles) + per module (NavigationModule + NavigationSections + Permissions + Roles). Check topological order. |
+| BA manifest not found | Create docs/index.json if missing. Use schema provided in section 3. |
+| Manifest entries incorrect | Verify appCode, moduleCode, and version match feature.json metadata exactly. |
+| ba-interactive.html is too small (< 100KB) | FEATURE_DATA not serialized correctly. Verify JSON structure. Re-run FEATURE_DATA build. |
+| moduleSpecs missing from HTML | FEATURE_DATA.moduleSpecs is empty or not included in JSON. Verify each module is iterated and populated. |
+| Scope keys still show "mustHave" instead of "vital" | Conversion from feature.json keys to HTML keys failed. Check cadrage.scope conversion logic. |
+| Wireframes array is empty | Verify each module has specification.uiWireframes. If missing, add wireframe stubs. |
+| dependencyGraph missing | Verify master feature.json has consolidation.dependencyGraph. If missing, create empty nodes/edges arrays. |
+| HTML opens but data blank (localStorage issue) | Clear browser localStorage. HTML will load pre-populated FEATURE_DATA on first load. |
+| Export/re-import fails | Verify exported JSON matches original feature.json schema. Validate with `/business-analyse -x --validate`. |