@atlashub/smartstack-cli 4.40.0 → 4.42.0

package/templates/skills/business-analyse-develop/steps/step-02-v4-verify.md

@@ -0,0 +1,156 @@
+---
+name: step-02-v4-verify
+description: Final verification gates, file reconciliation, BR coverage, and report generation
+model: opus
+---
+
+# Step 02-v4: Verify + Report
+
+## YOUR TASK
+
+After ALL modules are implemented, run final verification across the ENTIRE project, then generate the completion report.
+
+---
+
+## FINAL VERIFICATION SEQUENCE
+
+### 1. Full Solution Build
+
+```bash
+dotnet build 2>&1
+```
+
+This catches cross-module compilation issues that per-module builds might miss.
+
+### 2. Full Test Suite
+
+```bash
+dotnet test 2>&1
+```
+
+Run ALL tests across ALL modules. This catches cross-module integration issues.
+
+### 3. Frontend Verification
+
+```bash
+npm run typecheck 2>&1
+npm test -- --run 2>&1
+```
+
+### 4. File Reconciliation
+
+For each module's PRD, compare `expectedFiles` against actual files on disk:
+
+```javascript
+for (const category of ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation']) {
+  const expected = prd.expectedFiles[category] || [];
+  for (const file of expected) {
+    if (!existsOnDisk(file.path)) {
+      MISSING.push({ category, path: file.path, type: file.type });
+    }
+  }
+}
+```
+
+**If missing files found:**
+- List them clearly with category and expected path
+- Delegate to `/apex`: "Create missing files: {list}"
+- Re-verify after creation
+
+### 5. Business Rule Coverage
+
+For each BR in ALL modules' `brToCodeMapping`:
+1. Verify target file exists
+2. Verify implementation is present (grep for method/class name)
+3. Verify test coverage (grep test files for BR reference)
+
+Output:
+```
+BR Coverage: {covered}/{total} ({pct}%)
+Missing: BR-VAL-INV-003 (no test), BR-CALC-INV-005 (no implementation)
+```
+
+**If coverage < 100%:** Delegate remediation to `/apex`.
+
+### 6. MCP Final Scan
+
+```javascript
+// Security validation (BLOCKING)
+mcp__smartstack__validate_security({ projectPath: "." })
+
+// Convention validation (report)
+mcp__smartstack__validate_conventions({ projectPath: "." })
+
+// Code review — semantic permission check (BLOCKING if write endpoint has Read permission)
+mcp__smartstack__review_code({ files: changedFiles, focus: "security" })
+
+// Test convention validation (report)
+mcp__smartstack__validate_test_conventions({ projectPath: "." })
+```
+
+Log results. Security and permission mismatches are BLOCKING. Convention/test findings go in the report.
+
+---
+
+## REPORT GENERATION
+
+Generate `.ralph/reports/{feature}.md`:
+
+```markdown
+# Feature Report: {applicationName}
+
+**Generated:** {date}
+**Modules:** {moduleCount}
+**Duration:** {startTime} → {endTime}
+
+## Summary
+
+| Module | Entities | BRs | Sections | Build | Tests | Coverage |
+|--------|----------|-----|----------|-------|-------|----------|
+| {mod1} | {n}      | {n} | {n}      | PASS  | PASS  | {pct}%   |
+| {mod2} | {n}      | {n} | {n}      | PASS  | PASS  | {pct}%   |
+
+## Objectives
+
+| Objective | Status | Acceptance Criteria |
+|-----------|--------|---------------------|
+| {obj.description} | PASS/FAIL | {criteria results} |
+
+## File Reconciliation
+
+| Category | Expected | Present | Missing |
+|----------|----------|---------|---------|
+| domain | {n} | {n} | {list} |
+| ... | | | |
+
+## Business Rule Coverage
+
+| BR ID | Name | Implementation | Test | Status |
+|-------|------|----------------|------|--------|
+| {id} | {name} | {file}:{method} | {testFile} | PASS/FAIL |
+
+## Quality Gates
+
+| Gate | Result |
+|------|--------|
+| dotnet build | PASS |
+| dotnet test | PASS ({n} tests) |
+| npm typecheck | PASS |
+| npm test | PASS ({n} tests) |
+| MCP security | {findings} |
+| MCP conventions | {findings} |
+
+## Git Commits
+
+{list of commits with hashes and messages}
+```
+
+---
+
+## COMPLETION
+
+After report is generated:
+1. Display report path: `.ralph/reports/{feature}.md`
+2. Display summary stats
+3. If completion_promise was set: output the promise text
+4. Ralph-Loop is DONE

package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-04-check.md

@@ -382,7 +382,7 @@ If `hasPending && iteration < max`:
 ## CRITICAL RULES — EXECUTION GUARANTEE:
 
 - **NEVER** output completion promise unless ALL tasks done (all modules if multi)
-- **NEVER** stop between iterations — this is the CORE PROMISE of ralph-loop
+- **NEVER** stop between iterations — this is the CORE PROMISE of business-analyse-develop
 - **NEVER** ask the user "should I continue?" or "is this OK?" — JUST CONTINUE
 - **NEVER** pause to show intermediate results and wait for feedback
 - **NEVER** generate code directly — ALWAYS delegate to /apex

package/templates/skills/{ralph-loop → business-analyse-develop}/steps/step-05-report.md

@@ -365,7 +365,7 @@ if (prd._sectionSplit?.enabled && prd.status === 'completed') {
   }
   delete prd._sectionSplit;
 } else if (prd._sectionSplit?.enabled && prd.status !== 'completed') {
-  console.log(`Section-split temp files preserved (status: ${prd.status}) — use /ralph-loop -r to resume`);
+  console.log(`Section-split temp files preserved (status: ${prd.status}) — use /business-analyse-develop -r to resume`);
 }
 
 prd.updated_at = new Date().toISOString();

package/templates/skills/{derive-prd → business-analyse-handoff}/SKILL.md

@@ -1,20 +1,20 @@
 ---
-name: derive-prd
-description: "Transform consolidated business analysis into handoff data (8 categories) and PRD files for /ralph-loop consumption."
+name: business-analyse-handoff
+description: "Transform consolidated business analysis into handoff data (8 categories) and PRD files for /business-analyse-develop consumption."
 model: sonnet
 user_invocable: true
 ---
 
-# /derive-prd — v1
+# /business-analyse-handoff — v1
 
 ## Purpose
 
-Bridge between `/business-analyse` (understand) and `/ralph-loop` (execute).
+Bridge between `/business-analyse` (understand) and `/business-analyse-develop` (execute).
 Transforms consolidated BA data into structured handoff and PRD files.
 
 ```
-/business-analyse  →  /derive-prd  →  /ralph-loop
-   (comprendre)        (planifier)      (executer)
+/business-analyse  →  /business-analyse-handoff  →  /business-analyse-develop
+   (comprendre)            (planifier)               (executer)
 ```
 
 ## Architecture
@@ -38,7 +38,7 @@ Transforms consolidated BA data into structured handoff and PRD files.
 | Artifact | Path | Description |
 |----------|------|-------------|
 | Handoff data | Written to module `handoff.json` via ba-writer | 8-category file mapping + BR-to-code + API summary |
-| PRD files | `.ralph/prd-{moduleCode}.json` | Deterministic extraction via `ss derive-prd` |
+| PRD files | `.ralph/prd-{moduleCode}.json` | Deterministic extraction via `ss business-analyse-handoff` |
 | Progress tracker | `.ralph/progress.txt` | Task breakdown per module |
 | Module queue | `.ralph/modules-queue.json` | Topological order (if 2+ modules) |
 | BA manifest | `docs/index.json` | Updated with "handed-off" status |

package/templates/skills/{derive-prd → business-analyse-handoff}/references/acceptance-criteria.md

@@ -43,7 +43,7 @@ These verify data that `/business-analyse` produces:
 
 ### Output ACs (checked in step-01 post-transform)
 
-These verify data that `/derive-prd` step-01 generates:
+These verify data that `/business-analyse-handoff` step-01 generates:
 
 | # | Criterion | Minimum | Location | Blocking |
 |---|-----------|---------|----------|----------|
@@ -213,7 +213,7 @@ console.log('PASS: All output acceptance criteria met (AC-08 to AC-11)');
 | AC-05 | Re-run `/business-analyse` screen specification |
 | AC-06 | Re-run `/business-analyse` permission specification |
 | AC-07 | Run `/business-analyse` step-04 consolidation |
-| AC-08 | Re-run `/derive-prd` step-01 transform (missing categories) |
-| AC-09 | Re-run `/derive-prd` step-01 transform (BR mapping) |
-| AC-10 | Re-run `/derive-prd` step-01 transform (API endpoints) |
-| AC-11 | Re-run `/derive-prd` step-01 transform (seedData categories) |
+| AC-08 | Re-run `/business-analyse-handoff` step-01 transform (missing categories) |
+| 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) |

package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-file-templates.md

@@ -152,4 +152,4 @@ 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 `/ralph-loop` completes.
+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.

package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-mappings.md

@@ -44,7 +44,7 @@ When an entity has `personRoleConfig` in its entity data, it MUST be carried int
 | `personRoleConfig.userLinkMode` | Determines scaffold options: `isPersonRole: true, userLinkMode: "{mode}"` |
 | `personRoleConfig.inheritedFields` | Fields to exclude from entity (mandatory) or mark as fallback (optional) |
 
-The `personRoleConfig` object is passed through verbatim to ensure `/apex` and `/ralph-loop` receive the person extension configuration.
+The `personRoleConfig` object is passed through verbatim to ensure `/apex` and `/business-analyse-develop` receive the person extension configuration.
 
 ---
 

package/templates/skills/{derive-prd → business-analyse-handoff}/references/handoff-seeddata-generation.md

@@ -289,7 +289,7 @@ function inferIconFromModule(module) {
 IF !seedDataCore.navigationApplications || seedDataCore.navigationApplications.length === 0:
   BLOCKING ERROR: "navigationApplications is empty — Application navigation will NOT be seeded. Menu will show (nothing) → Modules."
 IF seedDataCore.navigationApplications[0].icon === null || seedDataCore.navigationApplications[0].icon === undefined:
-  BLOCKING ERROR: "Application icon is null — ralph-loop will render empty navigation"
+  BLOCKING ERROR: "Application icon is null — business-analyse-develop will render empty navigation"
 IF !seedDataCore.navigationApplications[0].labels?.fr || !seedDataCore.navigationApplications[0].labels?.en:
   BLOCKING ERROR: "Application labels missing fr/en — translations will fail"
 IF seedDataCore.navigationModules.length !== master.modules.length:
@@ -297,7 +297,7 @@ IF seedDataCore.navigationModules.length !== master.modules.length:
 IF seedDataCore.permissions.length === 0:
   WARNING: seedDataCore has 0 permissions — applicationRoles may be missing
 IF seedDataCore.navigationModules.some(m => !m.icon || m.icon === null):
-  BLOCKING ERROR: "Navigation modules with null icons detected — ralph-loop will render empty navigation"
+  BLOCKING ERROR: "Navigation modules with null icons detected — business-analyse-develop will render empty navigation"
   → Fix: Re-run inferIconFromModule() for modules with null icons
 IF seedDataCore.navigationSections.length === 0:
   WARNING: "0 navigation sections — every module should have at least 1 section (e.g., 'list')"

package/templates/skills/{derive-prd → business-analyse-handoff}/references/prd-generation.md

@@ -31,7 +31,7 @@ Example: `.ralph/prd-Projects.json`, `.ralph/prd-TimeTracking.json`
 **Common Error:**
 ```
 BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
-Fix: Re-run ss derive-prd with latest version
+Fix: Re-run ss business-analyse-handoff with latest version
 ```
 
 ---
@@ -75,7 +75,7 @@ Fix: Re-run ss derive-prd with latest version
 
 **Fix Command:**
 ```bash
-ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json
+ss business-analyse-handoff --feature {path} --output .ralph/prd-{moduleCode}.json
 ```
 
 ---
@@ -95,7 +95,7 @@ All PRD files MUST include these 8 categories under `implementation.filesToCreat
 | **tests** | Unit tests, integration tests | `ProjectServiceTests.cs`, `ProjectsControllerTests.cs` |
 | **documentation** | Technical docs, user guides, API specs | `doc-data.ts`, `UserGuide.md`, `api-spec.yaml` |
 
-> **Note `documentation`:** Cette catégorie peut contenir des fichiers générés par le skill `/documentation` après `/ralph-loop`. Elle est obligatoire dans la structure PRD (peut être un tableau vide `[]` si aucune doc n'est prévue, mais DOIT être présente).
+> **Note `documentation`:** Cette catégorie peut contenir des fichiers générés par le skill `/documentation` après `/business-analyse-develop`. Elle est obligatoire dans la structure PRD (peut être un tableau vide `[]` si aucune doc n'est prévue, mais DOIT être présente).
 
 **Validation:**
 ```javascript
@@ -136,7 +136,7 @@ for (const cat of categories) {
 **Why this matters:**
 - Ensures PRD was derived from the correct index.json
 - Catches stale PRD files (derived from old version)
-- Validates handoff integrity before ralph-loop
+- Validates handoff integrity before business-analyse-develop
 
 **Fix:**
 - Re-derive PRD from latest index.json
@@ -179,7 +179,7 @@ Use this checklist when validating PRD files:
 | **File Counts** | PRD counts match index.json handoff.filesToCreate | PASS/FAIL |
 | **File Schemas** | All files have path, type, module | PASS/FAIL |
 
-**All checks must PASS before proceeding to /ralph-loop**
+**All checks must PASS before proceeding to /business-analyse-develop**
 
 ---
 
@@ -189,13 +189,13 @@ Use this checklist when validating PRD files:
 ```
 BLOCKING_ERROR: PRD version must be 3.0.0, got: 2.1.0
 ```
-**Fix:** Re-run `ss derive-prd` with latest SmartStack.mcp version
+**Fix:** Re-run `ss business-analyse-handoff` with latest SmartStack.mcp version
 
 ### Error 2: filesToCreate at Root Level
 ```
 BLOCKING_ERROR: filesToCreate is at ROOT level (wrong structure)
 ```
-**Fix:** Re-run `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+**Fix:** Re-run `ss business-analyse-handoff --feature {path} --output .ralph/prd-{moduleCode}.json`
 
 ### Error 3: Missing Categories
 ```
@@ -212,7 +212,7 @@ BLOCKING_ERROR: api: prd has 8 files but index.json has 12
 ```
 **Fix:**
 - PRD is stale (derived from old index.json)
-- Re-derive PRD from latest index.json: `ss derive-prd --feature {path} --output .ralph/prd-{moduleCode}.json`
+- Re-derive PRD from latest index.json: `ss business-analyse-handoff --feature {path} --output .ralph/prd-{moduleCode}.json`
 
 ---
 
@@ -220,14 +220,14 @@ BLOCKING_ERROR: api: prd has 8 files but index.json has 12
 
 **Derive PRD from index.json:**
 ```bash
-ss derive-prd \
+ss business-analyse-handoff \
   --feature docs/{App}/business-analyse/v1.0/index.json \
   --output .ralph/prd-{ModuleCode}.json
 ```
 
 **Example:**
 ```bash
-ss derive-prd \
+ss business-analyse-handoff \
   --feature docs/HumanResources/business-analyse/v1.0/index.json \
   --output .ralph/prd-Projects.json
 ```
@@ -236,7 +236,7 @@ ss derive-prd \
 ```bash
 # Typically done in step-05-deploy.md
 for module in $(modules); do
-  ss derive-prd --feature {module_feature_path} --output .ralph/prd-${module}.json
+  ss business-analyse-handoff --feature {module_feature_path} --output .ralph/prd-${module}.json
 done
 ```
 
@@ -246,7 +246,7 @@ done
 
 | Risk | Without Validation | With Validation |
 |------|-------------------|-----------------|
-| **Wrong structure** | ralph-loop fails mid-execution | Caught before development starts |
+| **Wrong structure** | business-analyse-develop fails mid-execution | Caught before development starts |
 | **Stale PRD** | Generates code from old spec | Detects version mismatch |
 | **Missing files** | Incomplete implementation | Ensures all layers covered |
 | **Count mismatch** | Silent data loss | Guarantees integrity |
@@ -257,6 +257,6 @@ done
 
 ## Related Files
 
-- `step-05-deploy.md`: Generates PRD files via `ss derive-prd`
+- `step-05-deploy.md`: Generates PRD files via `ss business-analyse-handoff`
 - `feature-schema.json`: Schema for index.json (source of PRD)
-- `/ralph-loop` skill: Consumes PRD files for implementation
+- `/business-analyse-develop` skill: Consumes PRD files for implementation

package/templates/skills/{derive-prd → business-analyse-handoff}/schemas/handoff-schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "handoff-schema.json",
   "title": "SmartStack BA - Handoff",
-  "description": "Module-level handoff: file mapping (8 categories), BR-to-code mapping, API endpoint summary. Used by /derive-prd skill.",
+  "description": "Module-level handoff: file mapping (8 categories), BR-to-code mapping, API endpoint summary. Used by /business-analyse-handoff skill.",
   "type": "object",
   "properties": {
     "complexity": { "type": "string", "enum": ["simple", "medium", "complex"] },
@@ -61,7 +61,7 @@
     },
     "ralphPrd": {
       "type": "object",
-      "description": "Embedded Ralph Loop task breakdown (also exported to .ralph/prd.json by ss derive-prd)",
+      "description": "Embedded Ralph Loop task breakdown (also exported to .ralph/prd.json by ss business-analyse-handoff)",
       "properties": {
         "tasks": {
           "type": "array",

package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-00-validate.md

@@ -11,7 +11,7 @@ next_step: steps/step-01-transform.md
 
 ## MANDATORY EXECUTION RULES
 
-- **ALWAYS** verify status = "consolidated" or "specified" for all modules before proceeding
+- **ALWAYS** verify status = "consolidated", "specified", "designed", or "reviewed" for all modules before proceeding
 - **ALWAYS** validate **input** acceptance criteria (AC-01 to AC-07) per module
 - **ALWAYS** load flat files (entities.json, usecases.json, etc.) from module directories
 - **BLOCKING** if any module has readiness score < 100% on input ACs
@@ -33,14 +33,14 @@ IF --feature <path> provided:
   featurePath = <path>
 ELSE:
   // Auto-detect from docs/
-  Scan docs/ for index.json files with status = "consolidated"
+  Scan docs/ for index.json files with status in ["consolidated", "specified", "designed", "reviewed"]
   IF found exactly 1:
     featurePath = found path
   ELSE IF found > 1:
     Display list and ask user to specify --feature <path>
     STOP
   ELSE:
-    BLOCKING ERROR: "No consolidated BA feature found. Run /business-analyse first."
+    BLOCKING ERROR: "No ready BA feature found (expected status: consolidated, specified, designed, or reviewed). Run /business-analyse first."
     STOP
 ```
 
@@ -65,8 +65,8 @@ FOR each module in appIndex.modules:
 ```
 FOR each module:
   moduleIndex = READ(module.baDir/index.json)
-  IF moduleIndex.metadata.status NOT IN ["consolidated", "specified"]:
-    BLOCKING ERROR: "Module {module.code} status: {status}, expected consolidated or specified"
+  IF moduleIndex.metadata.status NOT IN ["consolidated", "specified", "designed", "reviewed"]:
+    BLOCKING ERROR: "Module {module.code} status: {status}, expected consolidated, specified, designed, or reviewed"
     -> Run /business-analyse to complete specification first
 ```
 
@@ -119,7 +119,7 @@ FOR each module:
   IF readiness_score < 100%:
     BLOCKING ERROR: "Module {moduleCode} readiness: {score}% -- {failed_count} input ACs failed"
     Display failed ACs with recovery actions
-    -> Run /business-analyse to fix, then retry /derive-prd
+    -> Run /business-analyse to fix, then retry /business-analyse-handoff
     STOP
 ```
 

package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-01-transform.md

@@ -35,11 +35,22 @@ For each module, load data from separate files:
 // Module BA directory: docs/{AppCode}/{ModuleCode}/business-analyse/v{X.Y}/
 const moduleDir = module.baDir;  // resolved in step-00
 
-const entities    = READ(moduleDir + '/entities.json').entities || [];
-const useCases    = READ(moduleDir + '/usecases.json').useCases || [];
-const rules       = READ(moduleDir + '/rules.json').rules || [];
-const permissions = READ(moduleDir + '/permissions.json');
-const screens     = READ(moduleDir + '/screens.json').screens || [];
+// Read with explicit error detection (do NOT silently swallow parse failures)
+const entitiesFile = READ(moduleDir + '/entities.json');
+const usecasesFile = READ(moduleDir + '/usecases.json');
+const rulesFile    = READ(moduleDir + '/rules.json');
+const permissions  = READ(moduleDir + '/permissions.json');
+const screensFile  = READ(moduleDir + '/screens.json');
+
+// Log missing files explicitly before falling back
+if (!entitiesFile) console.warn("⚠ " + moduleDir + "/entities.json not found — using empty");
+if (!usecasesFile) console.warn("⚠ " + moduleDir + "/usecases.json not found — using empty");
+if (!rulesFile)    console.warn("⚠ " + moduleDir + "/rules.json not found — using empty");
+
+const entities = (entitiesFile?.entities) || [];
+const useCases = (usecasesFile?.useCases) || [];
+const rules    = (rulesFile?.rules) || [];
+const screens  = (screensFile?.screens) || [];
 ```
 
 **Source mapping (flat files -> handoff categories):**
@@ -96,6 +107,24 @@ Since `/business-analyse` does not produce `apiEndpoints`, generate them from us
 // Map CRUD operations to HTTP methods
 ```
 
+### 2b. Enrich Sections with UC/BR Links
+
+Using `sectionCode` from usecases.json and rules.json, link each UC and BR to its section:
+
+```javascript
+// Build section-level UC/BR mapping
+const sectionMap = {};
+for (const section of screens) {
+  sectionMap[section.sectionCode || section.code] = {
+    useCases: useCases.filter(uc => uc.sectionCode === (section.sectionCode || section.code)).map(uc => uc.id),
+    businessRules: rules.filter(br => br.sectionCode === (section.sectionCode || section.code)).map(br => br.id)
+  };
+}
+// Attach to sections for PRD consumption
+```
+
+> This mapping enables business-analyse-develop's section-splitting to know which UCs/BRs belong to which section.
+
 ### 3. Map Specification to Files (8 Categories)
 
 > **Reference:** Read `references/handoff-file-templates.md` for complete JSON templates.
@@ -242,8 +271,18 @@ if (!handoff.brToCodeMapping || handoff.brToCodeMapping.length === 0) {
   BLOCKING_ERROR("Module {moduleCode}: brToCodeMapping is empty");
 }
 
-// 4. Display pass
-console.log("POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped");
+// 4. Validate section resources have entity field (enables section-splitting)
+const sections = screens || [];
+for (const section of sections) {
+  for (const resource of (section.resources || [])) {
+    if (!resource.entity) {
+      BLOCKING_ERROR("Module {moduleCode}, section {section.code}: resource {resource.code} missing 'entity' field");
+    }
+  }
+}
+
+// 5. Display pass
+console.log("POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {sections.length} sections validated");
 ```
 
 ---

package/templates/skills/{derive-prd → business-analyse-handoff}/steps/step-02-export.md

@@ -10,8 +10,8 @@ model: sonnet
 
 ## MANDATORY EXECUTION RULES
 
-- **ALWAYS** generate PRD via `ss derive-prd` CLI command (deterministic, never LLM)
-- **ALWAYS** verify PRD structure: $version=3.0.0, implementation.filesToCreate, 8 categories
+- **ALWAYS** generate PRD via `ss business-analyse-handoff` CLI command (deterministic, never LLM)
+- **ALWAYS** verify PRD structure: $version=3.0.0 or 4.0.0, implementation.filesToCreate (v3) or expectedFiles (v4), 8 categories
 - **ALWAYS** verify file counts match between PRD and handoff
 - **ALWAYS** generate progress.txt from template
 - **ALWAYS** update BA manifest (docs/index.json)
@@ -33,18 +33,30 @@ For EACH module:
 
 ```bash
 # Single module:
-ss derive-prd --ba-dir {moduleBaDir} --output .ralph/prd-{moduleCode}.json
+ss business-analyse-handoff --ba-dir {moduleBaDir} --output .ralph/prd-{moduleCode}.json
 
 # All modules from app-level index.json:
-ss derive-prd --ba-app {appIndexPath}
+ss business-analyse-handoff --ba-app {appIndexPath}
 ```
 
 **Option B — Legacy feature.json:**
 
 ```bash
-ss derive-prd --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
+ss business-analyse-handoff --feature {moduleFeaturePath} --output .ralph/prd-{moduleCode}.json
 ```
 
+**Option C — v4 spec-oriented PRD (1M context + compaction):**
+
+```bash
+ss business-analyse-handoff --ba-app {appIndexPath} --v4
+```
+
+Generates `prd-{moduleCode}.json` with `$version: "4.0.0"` containing:
+- `objectives[]` with acceptance criteria (instead of pre-computed tasks)
+- `expectedFiles` (same 8 categories, for file reconciliation)
+- `gates` (declarative quality gate definitions)
+- Architecture, business rules, BR mapping, seed data (same as v3)
+
 ### 2. POST-CHECK PRD (BLOCKING)
 
 > **Reference:** Read `references/prd-generation.md` for complete validation rules.
@@ -54,26 +66,27 @@ const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
 const featureHandoff = moduleFeature.handoff.filesToCreate;
 
 // Check 1: Version
-if (prd.$version !== "3.0.0") {
-  BLOCKING_ERROR("PRD version must be 3.0.0, got: " + prd.$version);
+if (prd.$version !== "3.0.0" && prd.$version !== "4.0.0") {
+  BLOCKING_ERROR("PRD version must be 3.0.0 or 4.0.0, got: " + prd.$version);
 }
 
-// Check 2: filesToCreate under implementation (not root)
-if (prd.filesToCreate && !prd.implementation?.filesToCreate) {
-  BLOCKING_ERROR("prd.json has filesToCreate at ROOT — not from ss derive-prd");
+// Check 2: filesToCreate location (v3: implementation.filesToCreate, v4: expectedFiles)
+const ftc = prd.$version === "4.0.0" ? prd.expectedFiles : prd.implementation?.filesToCreate;
+if (!ftc) {
+  BLOCKING_ERROR("prd.json missing file manifest (v3: implementation.filesToCreate, v4: expectedFiles)");
   STOP;
 }
 
 // Check 3: All 8 categories present
 const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
-const missingCategories = categories.filter(cat => !prd.implementation.filesToCreate[cat]);
+const missingCategories = categories.filter(cat => !ftc[cat]);
 if (missingCategories.length > 0) {
   BLOCKING_ERROR("Missing categories: " + missingCategories.join(', '));
 }
 
 // Check 4: File counts match
 for (const cat of categories) {
-  const prdCount = prd.implementation.filesToCreate[cat]?.length ?? 0;
+  const prdCount = ftc[cat]?.length ?? 0;
   const featureCount = featureHandoff[cat]?.length ?? 0;
   if (prdCount !== featureCount) {
     BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
@@ -111,6 +124,13 @@ Write to: `.ralph/modules-queue.json`
 - Summary with totals across all modules
 - Cross-module tasks IF multi-module
 
+Before writing:
+```
+IF .ralph/progress.txt exists AND contains "Iteration" entries:
+  WARN: "progress.txt contains development progress — appending handoff section instead of overwriting"
+  APPEND instead of WRITE
+```
+
 Write to: `.ralph/progress.txt`
 
 ### 5. Update BA Manifest (docs/index.json)
@@ -172,7 +192,7 @@ Artifacts generated:
   docs/index.json               — BA manifest (status: handed-off)
 
 [NEXT] Development:
-  1. Run /ralph-loop to begin implementation
+  1. Run /business-analyse-develop to begin implementation
   2. Modules will be processed in topological order
   3. Each module PRD contains {total_files} files across 8 categories
 
@@ -187,7 +207,7 @@ Artifacts generated:
 2. `.ralph/progress.txt` exists (>500 bytes)
 3. `.ralph/modules-queue.json` exists (if 2+ modules)
 4. `docs/index.json` updated with correct entry count and status "handed-off"
-5. All PRD files have $version=3.0.0, implementation.filesToCreate, 8 categories
+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
 
 **IF any check fails -> fix before completing.**

package/templates/skills/{ba-generate-html → business-analyse-html}/SKILL.md

@@ -1,19 +1,19 @@
 ---
-name: ba-generate-html
+name: business-analyse-html
 description: "Generate the interactive HTML document from business analysis JSON data"
 model: opus
 user_invocable: true
 ---
 
-# /ba-generate-html
+# /business-analyse-html
 
 Generate the interactive HTML document of the business analysis from the JSON analysis files.
 
 ## Triggers
 
-- Explicit invocation: `/ba-generate-html <feature-id>`
+- Explicit invocation: `/business-analyse-html <feature-id>`
 - After `/business-analyse` step-04 (consolidation complete)
-- Delegation from `/ba-review` (after review corrections applied)
+- Delegation from `/business-analyse-review` (after review corrections applied)
 
 ## Parameters