@atlashub/smartstack-cli 1.34.0 → 1.36.0

package/templates/skills/ralph-loop/steps/step-03-commit.md

@@ -1,6 +1,6 @@
 ---
 name: step-03-commit
-description: Commit changes, update prd.json and progress.txt
+description: Commit changes, update prd.json v2 with full tracking
 next_step: steps/step-04-check.md
 ---
 
@@ -8,7 +8,7 @@ next_step: steps/step-04-check.md
 
 ## YOUR TASK:
 
-Commit the changes from the executed task, update prd.json and progress.txt.
+Commit the changes from the executed task, finalize task tracking in prd.json, and append to history.
 
 ---
 
@@ -20,12 +20,16 @@ Commit the changes from the executed task, update prd.json and progress.txt.
 
 ```bash
 git add {files_created} {files_modified}
+
+# Also stage prd.json (already updated in step-02)
+git add .ralph/prd.json
 ```
 
 **Verify staged changes:**
 
 ```bash
 git status
+git diff --cached --stat
 ```
 
 ### 2. Create Commit
@@ -34,47 +38,107 @@ git status
 
 ```bash
 git commit -m "$(cat <<'EOF'
-feat(ralph): {current_task_description}
+{PREFIX}({scope}): {current_task_description}
 
 Task {current_task_id}/{tasks_total} - Iteration {current_iteration}
+Category: {current_task_category}
 
 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF
 )"
 ```
 
-**Commit message format:**
-- Type: `feat`, `fix`, `refactor`, `test`, `docs`
-- Scope: `ralph` or specific module
-- Description: Task description
-- Footer: Iteration info
+**Determine commit prefix from category:**
+
+| Category | Prefix | Scope |
+|----------|--------|-------|
+| `domain` | `feat` | entity name or module |
+| `application` | `feat` | module name |
+| `infrastructure` | `db` | migrations / config |
+| `api` | `feat` | controller name |
+| `frontend` | `feat` | component/page name |
+| `i18n` | `chore` | i18n |
+| `test` | `test` | module name |
+| `validation` | `chore` | validation |
+| `other` | `chore` | ralph |
+
+**Get commit hash:**
+```bash
+COMMIT_HASH=$(git rev-parse --short HEAD)
+```
+
+### 3. Finalize Task in prd.json
 
-### 3. Update prd.json
+**Mark task as completed with all tracking data:**
 
-**Mark current task as complete:**
+```javascript
+const prd = readJSON('.ralph/prd.json');
+const task = prd.tasks.find(t => t.id === {current_task_id});
+const now = new Date().toISOString();
 
-```json
-{
-  "feature": "{task_description}",
-  "current_iteration": {current_iteration + 1},
-  "tasks": [
-    { "id": 1, "description": "...", "passes": true },   // was false
-    { "id": 2, "description": "...", "passes": false }   // next task
-  ]
+// Only mark completed if not already failed in step-02
+if (task.status !== 'failed') {
+  task.status = 'completed';
+}
+task.completed_at = now;
+task.iteration = prd.config.current_iteration;
+task.commit_hash = COMMIT_HASH;
+
+// files_changed already set in step-02, but verify
+if (!task.files_changed || (!task.files_changed.created.length && !task.files_changed.modified.length)) {
+  // Fallback: extract from git diff
+  task.files_changed = {
+    created: getGitNewFiles(),    // git diff --cached --name-only --diff-filter=A
+    modified: getGitModifiedFiles() // git diff --cached --name-only --diff-filter=M
+  };
 }
 ```
 
-**Write updated prd.json:**
+### 4. Append to History
+
+**Add structured iteration entry:**
 
 ```javascript
-const prd = readJSON('.ralph/prd.json');
-const task = prd.tasks.find(t => t.id === currentTaskId);
-task.passes = true;
-prd.current_iteration++;
+prd.history.push({
+  iteration: prd.config.current_iteration,
+  task_id: task.id,
+  action: task.status,  // "completed" or "failed"
+  timestamp: now,
+  commit_hash: COMMIT_HASH,
+  duration_seconds: Math.round(
+    (new Date(now) - new Date(task.started_at)) / 1000
+  ),
+  notes: "{What was learned or accomplished during this task}"
+});
+```
+
+### 5. Increment Iteration and Update Timestamps
+
+**IMPORTANT: Increment AFTER recording the current iteration in task and history.**
+
+```javascript
+prd.config.current_iteration++;
+prd.updated_at = now;
+
+// Update top-level status
+const allCompleted = prd.tasks.every(t =>
+  t.status === 'completed' || t.status === 'skipped'
+);
+const anyFailed = prd.tasks.some(t => t.status === 'failed');
+const anyBlocked = prd.tasks.some(t => t.status === 'blocked');
+
+if (allCompleted) {
+  prd.status = 'completed';
+} else if (anyFailed || anyBlocked) {
+  prd.status = 'partial';
+} else {
+  prd.status = 'in_progress';
+}
+
 writeJSON('.ralph/prd.json', prd);
 ```
 
-### 4. Update progress.txt
+### 6. Update progress.txt
 
 **Append learnings to progress.txt:**
 
@@ -85,10 +149,17 @@ writeJSON('.ralph/prd.json', prd);
 
 ### Task Completed
 [{current_task_id}] {current_task_description}
+Category: {current_task_category}
+Status: {task.status}
+Commit: {COMMIT_HASH}
 
 ### Files Changed
-- Created: {files_created}
-- Modified: {files_modified}
+- Created: {task.files_changed.created}
+- Modified: {task.files_changed.modified}
+
+### Acceptance Criteria
+{current_task_criteria}
+Result: ✅ Met / ❌ Not met
 
 ### Learnings
 {What was learned during this task}
@@ -99,20 +170,38 @@ writeJSON('.ralph/prd.json', prd);
 {What the next iteration should know}
 ```
 
-### 5. Verify Commit
+### 7. Commit prd.json and progress.txt Updates
+
+**Stage and commit the tracking files separately:**
+
+```bash
+git add .ralph/prd.json .ralph/progress.txt
+git commit -m "$(cat <<'EOF'
+chore(ralph): update progress - task {current_task_id}/{tasks_total}
+
+Iteration {current_iteration} complete
+Status: {task.status}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+### 8. Verify Commit
 
 **Check commit was created:**
 
 ```bash
-git log -1 --oneline
+git log -2 --oneline
 ```
 
 **Expected output:**
 ```
-abc1234 feat(ralph): {current_task_description}
+def5678 chore(ralph): update progress - task {id}/{total}
+abc1234 feat(scope): {current_task_description}
 ```
 
-### 6. Log Activity (if verbose)
+### 9. Log Activity (if verbose)
 
 **If {verbose_mode} = true:**
 
@@ -120,9 +209,13 @@ Append to `.ralph/logs/{date}.log`:
 ```
 [{timestamp}] TASK COMPLETED
   Task: [{current_task_id}] {current_task_description}
-  Commit: {commit_hash}
-  Files: {file_count} changed
+  Category: {current_task_category}
+  Status: {task.status}
+  Commit: {COMMIT_HASH}
+  Files: {file_count} changed ({created_count} created, {modified_count} modified)
+  Duration: {duration_seconds}s
   Iteration: {current_iteration}
+  Validation: {validation_result}
 ```
 
 ---
@@ -134,13 +227,17 @@ Changes Committed:
 
 | Field | Value |
 |-------|-------|
-| Commit | {commit_hash} |
-| Task | [{current_task_id}] ✅ |
+| Commit | {COMMIT_HASH} |
+| Task | [{current_task_id}] {current_task_description} |
+| Category | {current_task_category} |
+| Status | {task.status} |
 | Iteration | {current_iteration} |
 | Files | {file_count} changed |
+| Duration | {duration_seconds}s |
+| Validation | {validation_result} |
 
-prd.json: Updated task {current_task_id} to passes: true
-progress.txt: Added iteration {current_iteration} learnings
+prd.json: Task {current_task_id} → {task.status}, history entry added
+progress.txt: Iteration {current_iteration} learnings appended
 
 -> Checking completion...
 ```
@@ -163,6 +260,13 @@ progress.txt: Added iteration {current_iteration} learnings
 2. Retry write
 3. If still fails, output error and stop
 
+**If task was failed in step-02:**
+
+1. Still commit whatever was done (partial progress)
+2. task.status remains "failed"
+3. history entry records action: "failed"
+4. step-04 will handle downstream blocking
+
 ---
 
 ## NEXT STEP:

package/templates/skills/ralph-loop/steps/step-04-check.md

@@ -1,6 +1,6 @@
 ---
 name: step-04-check
-description: Check completion criteria and decide next action
+description: Check completion criteria with status-based logic
 next_step: steps/step-05-report.md OR steps/step-01-task.md
 ---
 
@@ -8,7 +8,7 @@ next_step: steps/step-05-report.md OR steps/step-01-task.md
 
 ## YOUR TASK:
 
-Check if all tasks are complete and decide whether to output completion promise or continue to next task.
+Check if all tasks are complete and decide whether to output completion promise or continue to next task. Uses v2 status-based checks instead of boolean `passes`.
 
 ---
 
@@ -20,50 +20,74 @@ Check if all tasks are complete and decide whether to output completion promise
 
 ```javascript
 const prd = readJSON('.ralph/prd.json');
-const tasksCompleted = prd.tasks.filter(t => t.passes).length;
-const tasksTotal = prd.tasks.length;
-const allComplete = tasksCompleted === tasksTotal;
+
+const tasksCompleted = prd.tasks.filter(t => t.status === 'completed').length;
+const tasksSkipped   = prd.tasks.filter(t => t.status === 'skipped').length;
+const tasksFailed    = prd.tasks.filter(t => t.status === 'failed').length;
+const tasksBlocked   = prd.tasks.filter(t => t.status === 'blocked').length;
+const tasksPending   = prd.tasks.filter(t => t.status === 'pending').length;
+const tasksTotal     = prd.tasks.length;
+
+const allDone      = (tasksCompleted + tasksSkipped) === tasksTotal;
+const hasFailures  = tasksFailed > 0;
+const hasBlocked   = tasksBlocked > 0;
+const hasPending   = tasksPending > 0;
 ```
 
 ### 2. Check Iteration Limit
 
-**If {current_iteration} >= {max_iterations}:**
+**If `prd.config.current_iteration` > `prd.config.max_iterations`:**
 
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  ⚠️ MAX ITERATIONS REACHED                                        ║
+║  ⚠️ MAX ITERATIONS REACHED                                     ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Iterations: {current_iteration} / {max_iterations}               ║
-║  Tasks: {tasksCompleted} / {tasksTotal} complete                  ║
+║  Iterations: {current_iteration} / {max_iterations}             ║
+║  Tasks: {tasksCompleted} / {tasksTotal} complete                ║
+║  Failed: {tasksFailed}  |  Blocked: {tasksBlocked}             ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Ralph loop stopped due to iteration limit.                       ║
-║  Remaining tasks:                                                  ║
-║  {list of tasks with passes: false}                               ║
+║  Ralph loop stopped due to iteration limit.                     ║
+║  Remaining tasks:                                                ║
+║  {list of tasks with status != completed and != skipped}        ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 -> Generating partial report...
 ```
 
+**Update prd.json:**
+```javascript
+prd.status = 'partial';
+prd.updated_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prd);
+```
+
 **Proceed to step-05-report.md**
 
 ### 3. Check All Tasks Complete
 
-**If allComplete = true:**
+**If allDone = true:**
 
 ```
 ╔══════════════════════════════════════════════════════════════════╗
-║  ✅ ALL TASKS COMPLETE                                            ║
+║  ✅ ALL TASKS COMPLETE                                          ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Iterations: {current_iteration}                                  ║
-║  Tasks: {tasksTotal} / {tasksTotal} complete                      ║
+║  Iterations: {current_iteration - 1}                            ║
+║  Tasks: {tasksCompleted} completed, {tasksSkipped} skipped      ║
 ╠══════════════════════════════════════════════════════════════════╣
-║  Output completion promise:                                        ║
-║  <promise>{completion_promise}</promise>                          ║
+║  Output completion promise:                                      ║
+║  <promise>{completion_promise}</promise>                         ║
 ╚══════════════════════════════════════════════════════════════════╝
 
 <promise>{completion_promise}</promise>
 ```
 
+**Update prd.json:**
+```javascript
+prd.status = 'completed';
+prd.updated_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prd);
+```
+
 **CRITICAL: Output the promise tag exactly as shown:**
 ```
 <promise>{completion_promise}</promise>
@@ -71,15 +95,48 @@ const allComplete = tasksCompleted === tasksTotal;
 
 **Proceed to step-05-report.md**
 
-### 4. More Tasks Remaining
+### 4. Check for Dead-End (all remaining are blocked/failed)
+
+**If !hasPending AND !allDone:**
+
+All remaining tasks are blocked or failed. No progress is possible.
+
+```
+╔══════════════════════════════════════════════════════════════════╗
+║  ⚠️ DEAD-END DETECTED                                          ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Tasks: {tasksCompleted} completed, {tasksFailed} failed,       ║
+║         {tasksBlocked} blocked                                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  No more tasks can be executed.                                  ║
+║  Failed tasks:                                                   ║
+║  {list of failed tasks with error messages}                     ║
+║                                                                  ║
+║  Blocked tasks (downstream):                                     ║
+║  {list of blocked tasks with dependency info}                   ║
+╚══════════════════════════════════════════════════════════════════╝
+
+-> Generating partial report...
+```
+
+**Update prd.json:**
+```javascript
+prd.status = 'failed';
+prd.updated_at = new Date().toISOString();
+writeJSON('.ralph/prd.json', prd);
+```
+
+**Proceed to step-05-report.md**
+
+### 5. More Tasks Remaining
 
-**If allComplete = false AND iteration < max_iterations:**
+**If hasPending AND iteration < max_iterations:**
 
 ```
 Progress: {tasksCompleted} / {tasksTotal} tasks
+Failed: {tasksFailed}  |  Blocked: {tasksBlocked}  |  Pending: {tasksPending}
 
-Next task:
-[{next_task_id}] {next_task_description}
+Next eligible task will be determined by dependency resolution.
 
 Continuing to next iteration...
 ```
@@ -95,20 +152,25 @@ Continuing to next iteration...
                     │  Check Completion   │
                     └──────────┬──────────┘
                                │
-              ┌────────────────┼────────────────┐
-              │                │                │
-              ▼                ▼                ▼
-      ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-      │ Max Iters    │ │ All Tasks    │ │ Tasks        │
-      │ Reached      │ │ Complete     │ │ Remaining    │
-      └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
-             │                │                │
-             ▼                ▼                ▼
-      ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
-      │ Partial      │ │ Output       │ │ Loop to      │
-      │ Report       │ │ Promise      │ │ step-01      │
-      │ step-05      │ │ step-05      │ │              │
-      └──────────────┘ └──────────────┘ └──────────────┘
+          ┌────────────────────┼────────────────────┐
+          │                    │                    │
+          ▼                    ▼                    ▼
+   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+   │ Max Iters    │   │ All Tasks    │   │ Tasks        │
+   │ Reached      │   │ Done         │   │ Remaining    │
+   └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
+          │                  │                   │
+          │                  │          ┌────────┴────────┐
+          │                  │          │                 │
+          ▼                  ▼          ▼                 ▼
+   ┌──────────────┐   ┌──────────────┐ ┌─────────────┐ ┌─────────────┐
+   │ Partial      │   │ Output       │ │ Dead-End    │ │ Loop to     │
+   │ Report       │   │ Promise      │ │ (all blocked│ │ step-01     │
+   │ step-05      │   │ step-05      │ │ or failed)  │ │             │
+   │ status:      │   │ status:      │ │ step-05     │ │             │
+   │ "partial"    │   │ "completed"  │ │ status:     │ │             │
+   └──────────────┘   └──────────────┘ │ "failed"    │ └─────────────┘
+                                       └─────────────┘
 ```
 
 ---
@@ -122,9 +184,11 @@ Completion Check:
 | Field | Value |
 |-------|-------|
 | Iteration | {current_iteration} / {max_iterations} |
-| Tasks | {tasksCompleted} / {tasksTotal} |
+| Completed | {tasksCompleted} / {tasksTotal} |
+| Failed | {tasksFailed} |
+| Blocked | {tasksBlocked} |
+| Pending | {tasksPending} |
 | Status | Continuing |
-| Next | [{next_task_id}] {next_task_description} |
 
 -> Loading next task...
 ```
@@ -135,8 +199,9 @@ Completion Check:
 
 | Field | Value |
 |-------|-------|
-| Iteration | {current_iteration} |
-| Tasks | {tasksTotal} / {tasksTotal} |
+| Iterations Used | {current_iteration - 1} |
+| Completed | {tasksCompleted} / {tasksTotal} |
+| Skipped | {tasksSkipped} |
 | Status | COMPLETE |
 
 <promise>{completion_promise}</promise>
@@ -144,19 +209,38 @@ Completion Check:
 -> Generating report...
 ```
 
+**If partial/failed:**
+```
+Completion Check:
+
+| Field | Value |
+|-------|-------|
+| Iterations Used | {current_iteration - 1} |
+| Completed | {tasksCompleted} / {tasksTotal} |
+| Failed | {tasksFailed} |
+| Blocked | {tasksBlocked} |
+| Status | {PARTIAL or FAILED} |
+| Reason | {max iterations / dead-end} |
+
+-> Generating report...
+```
+
 ---
 
-## CRITICAL RULE:
+## CRITICAL RULES:
 
 **NEVER output the completion promise unless:**
-1. ALL tasks have `passes: true`
-2. The statement is genuinely true
+1. ALL tasks have `status: "completed"` or `status: "skipped"`
+2. Zero tasks with `status: "blocked"` or `status: "failed"`
+3. The statement is genuinely true
 
 **False promises to escape the loop are FORBIDDEN.**
 
+**Always update `prd.status` and `prd.updated_at` before proceeding.**
+
 ---
 
 ## NEXT STEP:
 
-- If complete or max iterations: `./step-05-report.md`
+- If complete or max iterations or dead-end: `./step-05-report.md`
 - If tasks remaining: `./step-01-task.md`