@atlashub/smartstack-cli 4.17.1 → 4.19.0

package/templates/skills/{business-analyse → derive-prd}/templates/tpl-progress.md

@@ -1,172 +1,172 @@
-# Progress Tracker Template (templates/tpl-progress.md)
-
-> **Used by:** step-05b-deploy (section 2: Initialize Progress Tracker)
-> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
-
-## Template
-
-```
-═════════════════════════════════════════════════════════════════
-  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
-  Project: {project_name} | Application: {app_name}
-  Modules: {count} ({moduleOrder.join(', ')})
-  Strategy: {implementation_strategy}
-  Created: {timestamp}
-  Status: HANDED-OFF
-═════════════════════════════════════════════════════════════════
-
-{For each module in topological order:}
-[MODULE: {module_name}] ({complexity})
-  Status: NOT STARTED
-  Dependencies: {list of module dependencies or "FOUNDATION"}
-
-  [DOMAIN] Entity & Value Object Definitions
-    □ Define {Entity1} entity with properties and validation
-    □ Define {Entity2} entity with relationships
-    □ Define {ValueObject1} value object
-    □ Define domain exceptions
-    □ Total: X tasks
-
-  [SEEDDATA-CORE] Core Configuration (MANDATORY)
-    □ NavigationApplicationSeedData - Application navigation entry (once per app)
-    □ ApplicationRolesSeedData - Application-scoped roles (once per app)
-    □ NavigationModuleSeedData - Module navigation structure (per module)
-    □ PermissionsSeedData - RBAC permissions (per module)
-    □ RolesSeedData - Role-permission mappings (per module)
-    □ {App}SeedDataProvider - IClientSeedDataProvider (4 methods)
-    Total: 2 app-level + 3 per-module + 1 provider
-
-  [SEEDDATA] Business Reference Data
-    □ Seed {Entity1} reference data
-    □ Seed {Entity2} lookup values
-    □ Total: Y business seed tasks
-
-  [APPLICATION] Services & Business Logic
-    □ Create {ServiceName}Service for {UC1}
-    □ Create {DtoName}Dto for API contracts
-    □ Create {ValidatorName}Validator for input validation
-    □ Implement query handlers
-    Total: Z tasks
-
-  [INFRASTRUCTURE] Repositories & Persistence
-    □ Create {Entity1}Repository with CRUD + custom queries
-    □ Create {Entity2}Repository
-    □ Configure DbContext for module
-    □ Setup specifications for complex queries
-    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
-    □ Create DevDataSeeder + SeedConstants (if first module)
-    □ Total: A tasks
-
-  [API] REST Endpoints & Controllers
-    □ Create {ModuleNameController} GET endpoints (List, GetById)
-    □ Create {ModuleNameController} POST endpoint (Create)
-    □ Create {ModuleNameController} PUT endpoint (Update)
-    □ Create {ModuleNameController} DELETE endpoint (Delete)
-    □ Implement error handling and validation responses
-    Total: B tasks
-
-  [FRONTEND] UI Components & Pages (wireframe-driven)
-    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
-    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
-    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
-    □ Create custom hook use{ModuleName}
-    □ Implement pagination, filtering, sorting
-    □ Validate all pages match their wireframe layout
-    □ ⚠️ Routes MUST be INSIDE the AppLayout wrapper
-    Total: C tasks
-
-  [I18N] Internationalization Keys
-    □ Define i18n keys for {Module} UI labels
-    □ Setup translations for locales: fr, en, it, de
-    Total: D keys
-
-  [TESTS] Unit & Integration Tests
-    □ Unit tests for {Entity} domain logic
-    □ Unit tests for {ServiceName}Service
-    □ Integration tests for {ModuleNameController}
-    □ Security tests for authorization & tenant isolation
-    □ E2E tests for critical user flows
-    Total: E unit + F integration + G security = H tests
-
-  [QA] Quality Assurance
-    □ Code review against SmartStack conventions
-    □ Test coverage minimum 80%
-    □ Security scan for OWASP vulnerabilities
-    □ Performance testing under load
-    Total: 4 QA tasks
-
-  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
-  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
-
-{If multi-module:}
-[CROSS-MODULE] Integration Tasks
-  Status: NOT STARTED
-  Dependencies: All modules COMPLETED
-
-  □ Verify cross-module entity relationships
-  □ Test cross-module API dependencies
-  □ Validate permission matrix across modules
-  □ E2E flow tests spanning multiple modules
-  □ Cross-module data consistency checks
-  □ Integration test suite for module interactions
-  Total: 6 CROSS-MODULE tasks
-
-═════════════════════════════════════════════════════════════════
-SUMMARY
-═════════════════════════════════════════════════════════════════
-Total Modules:         {count}
-Total Tasks:           {total_count}
-  - CORE SeedData:     {count} × 5 = {total_core}
-  - Business Tasks:    {total_biz}
-  - Development:       {total_dev}
-  - Tests:             {total_tests}
-  - QA:                {total_qa}
-  - Cross-Module:      {cross_module_count or 0}
-
-Strategy:              {strategy}
-Module Order:          {topological order with dependencies noted}
-
-Complexity Distribution:
-  Simple:   {count} modules ({estimate} days each)
-  Medium:   {count} modules ({estimate} days each)
-  Complex:  {count} modules ({estimate} days each)
-
-Total Effort Estimate:  {total_days} days ({total_hours} hours)
-Per Developer (2):      {total_days / 2} days
-Parallel Potential:     {strategy_efficiency_percent}%
-
-═════════════════════════════════════════════════════════════════
-LEGEND
-═════════════════════════════════════════════════════════════════
-□ = Task not started
-✓ = Task completed
-⚠ = Task in progress
-✗ = Task failed / blocked
-
-COLORS:
-[DOMAIN]      = Domain Model & Business Logic
-[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
-[SEEDDATA]    = Business reference & lookup data
-[APPLICATION] = Services, DTOs, Validators
-[INFRASTRUCTURE] = Repositories, DbContext, ORM
-[API]         = REST controllers & endpoints
-[FRONTEND]    = React pages, components, hooks
-[I18N]        = Internationalization
-[TESTS]       = Unit, Integration, Security, E2E
-[QA]          = Code quality, coverage, security
-[CROSS-MODULE] = Multi-module integration (if applicable)
-
-═════════════════════════════════════════════════════════════════
-```
-
-## Progress Tracker Rules
-
-- One section per module, in topological order (dependencies first)
-- CORE SeedData ALWAYS 5 entries (mandatory)
-- Business SeedData varies by module
-- Hierarchical task structure (module → layer → tasks)
-- Each task is independent, assignable checkbox
-- Effort estimate per module (simple/medium/complex)
-- Summary with totals across all modules
-- Identified dependencies for parallel execution
-- Cross-module tasks only if multi-module
+# Progress Tracker Template (templates/tpl-progress.md)
+
+> **Used by:** step-05-deploy (section 4: Generate progress.txt)
+> **Purpose:** Template structure for .ralph/progress.txt - populate with module-specific data
+
+## Template
+
+```
+═════════════════════════════════════════════════════════════════
+  SMARTSTACK RALPH LOOP - PROGRESS TRACKER
+  Project: {project_name} | Application: {app_name}
+  Modules: {count} ({moduleOrder.join(', ')})
+  Strategy: {implementation_strategy}
+  Created: {timestamp}
+  Status: HANDED-OFF
+═════════════════════════════════════════════════════════════════
+
+{For each module in topological order:}
+[MODULE: {module_name}] ({complexity})
+  Status: NOT STARTED
+  Dependencies: {list of module dependencies or "FOUNDATION"}
+
+  [DOMAIN] Entity & Value Object Definitions
+    □ Define {Entity1} entity with properties and validation
+    □ Define {Entity2} entity with relationships
+    □ Define {ValueObject1} value object
+    □ Define domain exceptions
+    □ Total: X tasks
+
+  [SEEDDATA-CORE] Core Configuration (MANDATORY)
+    □ NavigationApplicationSeedData - Application navigation entry (once per app)
+    □ ApplicationRolesSeedData - Application-scoped roles (once per app)
+    □ NavigationModuleSeedData - Module navigation structure (per module)
+    □ PermissionsSeedData - RBAC permissions (per module)
+    □ RolesSeedData - Role-permission mappings (per module)
+    □ {App}SeedDataProvider - IClientSeedDataProvider (4 methods)
+    Total: 2 app-level + 3 per-module + 1 provider
+
+  [SEEDDATA] Business Reference Data
+    □ Seed {Entity1} reference data
+    □ Seed {Entity2} lookup values
+    □ Total: Y business seed tasks
+
+  [APPLICATION] Services & Business Logic
+    □ Create {ServiceName}Service for {UC1}
+    □ Create {DtoName}Dto for API contracts
+    □ Create {ValidatorName}Validator for input validation
+    □ Implement query handlers
+    Total: Z tasks
+
+  [INFRASTRUCTURE] Repositories & Persistence
+    □ Create {Entity1}Repository with CRUD + custom queries
+    □ Create {Entity2}Repository
+    □ Configure DbContext for module
+    □ Setup specifications for complex queries
+    □ Create IClientSeedDataProvider (client projects ONLY - injects core seeds at runtime)
+    □ Create DevDataSeeder + SeedConstants (if first module)
+    □ Total: A tasks
+
+  [API] REST Endpoints & Controllers
+    □ Create {ModuleNameController} GET endpoints (List, GetById)
+    □ Create {ModuleNameController} POST endpoint (Create)
+    □ Create {ModuleNameController} PUT endpoint (Update)
+    □ Create {ModuleNameController} DELETE endpoint (Delete)
+    □ Implement error handling and validation responses
+    Total: B tasks
+
+  [FRONTEND] UI Components & Pages (wireframe-driven)
+    □ Create {ModuleName}Page for listing [wireframe: {module}-list]
+    □ Create {ModuleName}DetailPage for viewing [wireframe: {module}-detail]
+    □ Create {ModuleName}Form component for creation/edit [wireframe: {module}-create]
+    □ Create custom hook use{ModuleName}
+    □ Implement pagination, filtering, sorting
+    □ Validate all pages match their wireframe layout
+    □ ⚠️ Routes MUST be INSIDE the AppLayout wrapper
+    Total: C tasks
+
+  [I18N] Internationalization Keys
+    □ Define i18n keys for {Module} UI labels
+    □ Setup translations for locales: fr, en, it, de
+    Total: D keys
+
+  [TESTS] Unit & Integration Tests
+    □ Unit tests for {Entity} domain logic
+    □ Unit tests for {ServiceName}Service
+    □ Integration tests for {ModuleNameController}
+    □ Security tests for authorization & tenant isolation
+    □ E2E tests for critical user flows
+    Total: E unit + F integration + G security = H tests
+
+  [QA] Quality Assurance
+    □ Code review against SmartStack conventions
+    □ Test coverage minimum 80%
+    □ Security scan for OWASP vulnerabilities
+    □ Performance testing under load
+    Total: 4 QA tasks
+
+  Module Total: X + 5 + Y + Z + A + B + C + D + H + 4 = {module_total} tasks
+  Estimated Effort: {simple/medium/complex} - {1-3/3-8/8-15} days
+
+{If multi-module:}
+[CROSS-MODULE] Integration Tasks
+  Status: NOT STARTED
+  Dependencies: All modules COMPLETED
+
+  □ Verify cross-module entity relationships
+  □ Test cross-module API dependencies
+  □ Validate permission matrix across modules
+  □ E2E flow tests spanning multiple modules
+  □ Cross-module data consistency checks
+  □ Integration test suite for module interactions
+  Total: 6 CROSS-MODULE tasks
+
+═════════════════════════════════════════════════════════════════
+SUMMARY
+═════════════════════════════════════════════════════════════════
+Total Modules:         {count}
+Total Tasks:           {total_count}
+  - CORE SeedData:     {count} × 5 = {total_core}
+  - Business Tasks:    {total_biz}
+  - Development:       {total_dev}
+  - Tests:             {total_tests}
+  - QA:                {total_qa}
+  - Cross-Module:      {cross_module_count or 0}
+
+Strategy:              {strategy}
+Module Order:          {topological order with dependencies noted}
+
+Complexity Distribution:
+  Simple:   {count} modules ({estimate} days each)
+  Medium:   {count} modules ({estimate} days each)
+  Complex:  {count} modules ({estimate} days each)
+
+Total Effort Estimate:  {total_days} days ({total_hours} hours)
+Per Developer (2):      {total_days / 2} days
+Parallel Potential:     {strategy_efficiency_percent}%
+
+═════════════════════════════════════════════════════════════════
+LEGEND
+═════════════════════════════════════════════════════════════════
+□ = Task not started
+✓ = Task completed
+⚠ = Task in progress
+✗ = Task failed / blocked
+
+COLORS:
+[DOMAIN]      = Domain Model & Business Logic
+[SEEDDATA-CORE] = MANDATORY core configuration (5 entries)
+[SEEDDATA]    = Business reference & lookup data
+[APPLICATION] = Services, DTOs, Validators
+[INFRASTRUCTURE] = Repositories, DbContext, ORM
+[API]         = REST controllers & endpoints
+[FRONTEND]    = React pages, components, hooks
+[I18N]        = Internationalization
+[TESTS]       = Unit, Integration, Security, E2E
+[QA]          = Code quality, coverage, security
+[CROSS-MODULE] = Multi-module integration (if applicable)
+
+═════════════════════════════════════════════════════════════════
+```
+
+## Progress Tracker Rules
+
+- One section per module, in topological order (dependencies first)
+- CORE SeedData ALWAYS 5 entries (mandatory)
+- Business SeedData varies by module
+- Hierarchical task structure (module → layer → tasks)
+- Each task is independent, assignable checkbox
+- Effort estimate per module (simple/medium/complex)
+- Summary with totals across all modules
+- Identified dependencies for parallel execution
+- Cross-module tasks only if multi-module

package/templates/skills/ralph-loop/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
 ---
 
 <objective>
-Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/business-analyse`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
+Execute the Ralph Weegund technique — iterative module orchestration. Ralph reads PRDs from `/derive-prd`, resolves task dependencies, and delegates all code generation to `/apex -d`. Uses progress persistence and Agent Teams for multi-module parallelization.
 
 **Key principle:** Ralph ORCHESTRATES (task selection, module sequencing, PRD state, reporting). All code generation is delegated to `/apex`.
 </objective>
@@ -15,6 +15,7 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 **From Business Analysis (RECOMMENDED):**
 ```bash
 /business-analyse MyFeature
+# Then: /derive-prd
 # Then: /ralph-loop -r
 ```
 
@@ -43,9 +44,9 @@ Execute the Ralph Weegund technique — iterative module orchestration. Ralph re
 
 **Single module:**
 1. Init: parse flags, verify MCP, setup .ralph/ (step-00)
-2. Load tasks from prd.json — unified v3 has pre-computed tasks (step-01, READ ONCE)
-3. Execute first task (step-02, READ ONCE)
-4. Commit + update progress (step-03, READ ONCE)
+2. Load tasks from prd.json — unified v3 has pre-computed tasks (step-01, step FILE read once)
+3. Execute first task (step-02, step FILE read once)
+4. Commit + update progress (step-03, step FILE read once)
 5. Check completion → enter COMPACT LOOP (step-04)
 6. **COMPACT LOOP** (step-04 → references/compact-loop.md):
    - Find eligible → batch by category (max 5) → execute → test → commit → loop
@@ -105,6 +106,7 @@ LOAD → DELEGATE TO /apex -d → VERIFY PRD STATE → COMMIT PRD → NEXT MODUL
 | `{section_phases}` | SectionPhase[] | Phase execution plan (Phase 0: foundation, Phase 1..N: per-section) |
 | `{parallel_mode}` | boolean | Teams mode enabled via `-p` flag. Ralph generates Phase 0 (entities) sequentially, then spawns parallel teammates. |
 | `{team_name}` | string\|null | Team name for parallel mode (e.g., "smartstack-hr") |
+| `{team_active}` | boolean | True after `TeamCreate`, false after `TeamDelete`. Used in step-04 section 3a to send `MODULE_COMPLETE` to team-lead instead of advancing the module queue locally. |
 </state_variables>
 
 <mcp_requirements>
@@ -162,6 +164,10 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 | 04 | `steps/step-04-check.md` | Check completion, compact loop entry | ~185 |
 | 05 | `steps/step-05-report.md` | Generate final report | ~150 |
 
+> **"Read Once" rule:** Each **step file** (step-01 to step-04) is loaded only once at the start of the first iteration. From iteration 2 onward, `compact-loop.md` drives the loop inline — step files are NOT re-read. This reduces context consumption. **Exception:** prd.json is re-read every iteration (it changes); step files are not.
+
+> **Distinction:** `/apex -d prd.json` is invoked every iteration (B2 of compact-loop) — that is normal and expected. "Read Once" applies only to the step instruction files, not to data files or apex delegations.
+
 **Reference files (loaded conditionally):**
 | File | Loaded when |
 |------|-------------|

package/templates/skills/ralph-loop/references/category-completeness.md

@@ -151,14 +151,30 @@ if (guardrailsNeeded.length > 0) {
 
 ## Artifact Verification
 
-After category check, verify artifacts actually exist for completed tasks:
+After category check, verify artifacts actually exist for completed tasks.
+
+> **Patterns read from PRD metadata first** (`prd.metadata.artifactPatterns`), falling back to SmartStack defaults.
+> This allows non-standard project structures to work without hardcoded paths.
 
 ```javascript
 const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+
+// Read custom patterns from PRD metadata (set by ss derive-prd based on project structure)
+const customPatterns = prd.metadata?.artifactPatterns || {};
+
 const artifactChecks = {
-  'frontend': () => glob.sync('**/src/pages/**/*.tsx').length > 0,
-  'test': () => glob.sync('tests/**/*Tests.cs').length > 0,
-  'api': () => glob.sync('src/*/Controllers/**/*Controller.cs').length > 0
+  'frontend': () => {
+    const patterns = customPatterns.frontend || ['**/src/pages/**/*.tsx', '**/src/app/**/*.tsx'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  },
+  'test': () => {
+    const patterns = customPatterns.test || ['tests/**/*Tests.cs', '**/*.spec.ts', '**/*.test.ts'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  },
+  'api': () => {
+    const patterns = customPatterns.api || ['src/*/Controllers/**/*Controller.cs', 'src/**/controllers/**/*.ts'];
+    return patterns.some(p => glob.sync(p).length > 0);
+  }
 };
 
 for (const [cat, check] of Object.entries(artifactChecks)) {

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -36,7 +36,7 @@ if (prd._sectionSplit?.enabled) {
 
   if (!nextPhase) {
     // All phases done — check if master PRD tasks are all complete
-    goto CHECK_COMPLETION;
+    // → STOP this section. Return to step-04 section 1 (CHECK_COMPLETION path).
   }
 
   const depsOk = nextPhase.dependsOn.every(depIdx =>
@@ -46,7 +46,7 @@ if (prd._sectionSplit?.enabled) {
   if (!depsOk) {
     // Phase blocked — should not happen with topological sort
     console.warn(`Phase ${nextPhase.phase} blocked — dependencies incomplete`);
-    goto CHECK_COMPLETION;
+    // → STOP this section. Return to step-04 section 1 (CHECK_COMPLETION path).
   }
 
   const phaseLabel = nextPhase.type === 'foundation'
@@ -54,11 +54,14 @@ if (prd._sectionSplit?.enabled) {
     : `Phase ${nextPhase.phase}: Section "${nextPhase.sectionCode}" (${nextPhase.entities.length} entities)`;
   console.log(`[{iteration}/{max}] SECTION SPLIT: ${phaseLabel}`);
 
-  // INVOKE /apex -d {nextPhase.prdFile}
-  // Apex sees a normal (smaller) PRD and executes normally
+  // ↓ MANDATORY: execute this skill call now (not pseudo-code)
+```
+
+**INVOKE `/apex -d {nextPhase.prdFile}`**
+
+Apex sees a focused PRD for this phase only. After apex returns, continue:
 
-  // After apex returns: merge results back into master PRD
-  // Read references/section-splitting.md sections 7-9
+```javascript
   const phasePrd = readJSON(nextPhase.prdFile);
   for (const phaseTask of phasePrd.tasks) {
     const masterTask = prd.tasks.find(t => t.id === phaseTask.id);
@@ -96,7 +99,7 @@ if (prd._sectionSplit?.enabled) {
   writeJSON('.ralph/prd.json', prd);
 
   // → Skip to section C (commit PRD state), then D (loop back)
-  goto COMMIT_PRD;
+  // → SKIP sections A and B. Jump directly to section C (COMMIT_PRD) below.
 }
 ```
 
@@ -112,43 +115,65 @@ if (prd._sectionSplit?.enabled) {
 ```javascript
 const MAX_RETRIES = 3;
 
+// DEAD-END PRE-CHECK: verify if we are truly stuck BEFORE resetting retries.
+// Resetting retries FIRST would mask a dead-end — the check must run on the raw state.
+const failedBeforeRetry = prd.tasks.filter(t => t.status === 'failed');
+const retriableBeforeReset = failedBeforeRetry.filter(t => (t._retryCount || 0) < MAX_RETRIES);
+const hasPendingBeforeRetry = prd.tasks.some(t => t.status === 'pending');
+const allDoneBeforeRetry = prd.tasks.every(t => t.status === 'completed' || t.status === 'skipped');
+
+const isDeadEnd = !hasPendingBeforeRetry && !allDoneBeforeRetry && retriableBeforeReset.length === 0;
+
+if (isDeadEnd) {
+  // TRUE dead-end: no pending tasks, not all done, and no retries left.
+  // Mark prd.status = 'failed' NOW so step-04 section 4 routes to step-05.
+  // Then fall through to `eligible.length === 0` below which returns to step-04.
+  console.log(`DEAD-END: ${prd.tasks.filter(t=>t.status==='completed').length} done, ${failedBeforeRetry.length} failed (retries exhausted), ${prd.tasks.filter(t=>t.status==='blocked').length} blocked`);
+  prd.status = 'failed';
+  writeJSON('.ralph/prd.json', prd);
+  // DO NOT reset retries below — skip to eligible search (will find 0 tasks → CHECK_COMPLETION)
+}
+
 // RETRY: Reset failed tasks to pending if retries remain (max 3 attempts per task)
-for (const task of prd.tasks) {
-  if (task.status !== 'failed') continue;
-  const retryCount = task._retryCount || 0;
-  if (retryCount < MAX_RETRIES) {
-    task.status = 'pending';
-    task._retryCount = retryCount + 1;
-    task.error = null;
-    console.log(`RETRY [${task.id}] attempt ${retryCount + 1}/${MAX_RETRIES}: ${task.description.substring(0, 60)}`);
+// Skipped when isDeadEnd = true (no retriable tasks remain anyway).
+if (!isDeadEnd) {
+  for (const task of prd.tasks) {
+    if (task.status !== 'failed') continue;
+    const retryCount = task._retryCount || 0;
+    if (retryCount < MAX_RETRIES) {
+      task.status = 'pending';
+      task._retryCount = retryCount + 1;
+      task.error = null;
+      console.log(`RETRY [${task.id}] attempt ${retryCount + 1}/${MAX_RETRIES}: ${task.description.substring(0, 60)}`);
+    }
   }
-}
 
-// Unblock tasks whose dependencies are no longer failed (due to retries above)
-for (const task of prd.tasks) {
-  if (task.status !== 'blocked') continue;
-  const stillBlocked = task.dependencies.some(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && (dep.status === 'failed' || dep.status === 'blocked');
-  });
-  if (!stillBlocked) {
-    task.status = 'pending';
-    task.error = null;
-    console.log(`UNBLOCKED [${task.id}]: dependencies resolved`);
+  // Unblock tasks whose dependencies are no longer failed (due to retries above)
+  for (const task of prd.tasks) {
+    if (task.status !== 'blocked') continue;
+    const stillBlocked = task.dependencies.some(depId => {
+      const dep = prd.tasks.find(t => t.id === depId);
+      return dep && (dep.status === 'failed' || dep.status === 'blocked');
+    });
+    if (!stillBlocked) {
+      task.status = 'pending';
+      task.error = null;
+      console.log(`UNBLOCKED [${task.id}]: dependencies resolved`);
+    }
   }
-}
 
-// Block pending tasks whose dependencies are still failed/blocked
-for (const task of prd.tasks) {
-  if (task.status !== 'pending') continue;
-  const depsBlocked = task.dependencies.some(depId => {
-    const dep = prd.tasks.find(t => t.id === depId);
-    return dep && (dep.status === 'failed' || dep.status === 'blocked');
-  });
-  if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
-}
+  // Block pending tasks whose dependencies are still failed/blocked
+  for (const task of prd.tasks) {
+    if (task.status !== 'pending') continue;
+    const depsBlocked = task.dependencies.some(depId => {
+      const dep = prd.tasks.find(t => t.id === depId);
+      return dep && (dep.status === 'failed' || dep.status === 'blocked');
+    });
+    if (depsBlocked) { task.status = 'blocked'; task.error = 'Blocked by failed dependency'; }
+  }
 
-writeJSON('.ralph/prd.json', prd);
+  writeJSON('.ralph/prd.json', prd);
+} // end if (!isDeadEnd)
 
 // Find ALL eligible tasks (dependencies met)
 const eligible = prd.tasks.filter(task => {
@@ -160,8 +185,8 @@ const eligible = prd.tasks.filter(task => {
 });
 
 if (eligible.length === 0) {
-  // Dead-end or all done — return to step-04 sections 2-4
-  goto CHECK_COMPLETION;
+  // All done or dead-end — return to step-04 sections 2-4
+  // [goto CHECK_COMPLETION]
 }
 
 // BATCH: group by category, take first group (max 5)
@@ -265,21 +290,28 @@ chore(ralph): update PRD state — iteration {iteration}
 Tasks: {completed}/{batch_size} completed via /apex
 Overall: {totalCompleted}/{total}
 
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+Co-Authored-By: Claude AI <noreply@anthropic.com>
 EOF
 )"
 ```
 
 ### C4. PRD Sync Verification (HARD CHECK)
 
-```javascript
-const prdVerify = readJSON('.ralph/prd.json');
-const actuallyCompleted = prdVerify.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed');
+> **Note:** `prdCheck` (read in C1) is the authoritative post-apex snapshot.
+> `completed` (from B3) was computed on a DIFFERENT read — do NOT mix the two.
+> Re-derive the count from `prdCheck` to avoid stale-reference mismatches.
 
-if (actuallyCompleted.length !== completed) {
-  console.error('PRD SYNC ERROR: Mismatch between apex results and prd.json');
-  // Force re-read — apex may have written after our read
-  // DO NOT overwrite — apex is the source of truth for task statuses
+```javascript
+// Re-derive completed count from the SAME object used for the commit (prdCheck)
+const actuallyCompleted = prdCheck.tasks.filter(t => batchIds.includes(t.id) && t.status === 'completed').length;
+const actuallyFailed    = prdCheck.tasks.filter(t => batchIds.includes(t.id) && t.status === 'failed').length;
+
+if (actuallyCompleted !== completed) {
+  console.warn(`PRD SYNC WARNING: B3 reported ${completed} completed, prdCheck shows ${actuallyCompleted}`);
+  console.warn('Using prdCheck as source of truth (apex may have written between reads)');
+  // DO NOT overwrite prdCheck — apex is the source of truth for task statuses
+  // Update local `completed` variable for progress reporting consistency
+  completed = actuallyCompleted;
 }
 ```
 

package/templates/skills/ralph-loop/references/init-resume-recovery.md

@@ -88,7 +88,9 @@ if (handoffStatus === 'handed-off') {
   console.log('BA artifacts detected without PRD — auto-recovering...');
 
   // Call ss derive-prd to generate PRD files
-  const result = exec(`ss derive-prd --application ${masterFeature}`);
+  // Flag: --feature (path to feature.json) — matches ss derive-prd CLI convention
+  // See also: step-05c-ralph-readiness.md section 2 "Fix: ss derive-prd --feature {path} --output ..."
+  const result = exec(`ss derive-prd --feature ${masterFeature}`);
 
   if (result.exitCode !== 0) {
     console.error('ss derive-prd failed — cannot auto-recover');
@@ -107,7 +109,7 @@ if (handoffStatus === 'handed-off') {
   // BA handoff NOT complete
   console.warn(`⚠ BA handoff status: "${handoffStatus}" (expected "handed-off")`);
   console.warn('Cannot auto-recover PRD files without complete handoff');
-  console.warn('Run /business-analyse to complete the handoff, then retry /ralph-loop');
+  console.warn('Run /derive-prd to generate the handoff, then retry /ralph-loop');
   STOP;
 }
 ```