@atlashub/smartstack-cli 3.37.0 → 3.38.0

package/templates/skills/gitflow/steps/step-pr.md

@@ -99,101 +99,16 @@ EXISTING_PR=$(gh pr list --head "$CURRENT" --json number --jq '.[0].number' 2>/d
 
 ### 4. Run Pre-PR Checks
 
-```bash
-# Build check (multi-runtime detection)
-echo "Running build check..."
-if [ -f "*.sln" ] || ls *.csproj 2>/dev/null | head -1 > /dev/null; then
-  dotnet build --no-restore 2>&1 || {
-    echo "❌ .NET build failed. Fix before creating PR."
-    STOP
-  }
-  # Migration check
-  echo "Checking migrations..."
-  dotnet ef migrations list 2>&1 || echo "No migrations or EF Core not configured"
-elif [ -f "package.json" ]; then
-  npm run build 2>&1 || {
-    echo "❌ npm build failed. Fix before creating PR."
-    STOP
-  }
-elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
-  echo "Python project detected — skipping build check"
-else
-  echo "⚠️ No known build system detected — skipping build check"
-fi
-```
-
-### 4b. Enforce Migration Squash (Feature Branches)
-
-**BLOCKING**: Feature branches must have at most 1 migration before creating a PR.
-
-```bash
-if [ "$BRANCH_TYPE" = "feature" ]; then
-  MIGRATION_DIR=$(find . -path "*/Persistence/Migrations" -type d 2>/dev/null | head -1)
-  if [ -n "$MIGRATION_DIR" ]; then
-    # Count migration .cs files added by this feature (not in target branch)
-    NEW_MIGRATIONS=$(git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
-      | grep -E '\.cs$' \
-      | grep -v 'Designer\|ModelSnapshot' \
-      | wc -l)
-
-    if [ "$NEW_MIGRATIONS" -gt 1 ]; then
-      echo ""
-      echo "❌ MULTIPLE MIGRATIONS DETECTED ($NEW_MIGRATIONS migrations)"
-      echo "→ Feature branches must have exactly 1 migration (squashed) before PR"
-      echo "→ Run: /efcore squash"
-      echo ""
-      echo "Migrations found:"
-      git diff --name-only "origin/$TARGET_BRANCH...HEAD" -- "$MIGRATION_DIR" \
-        | grep -E '\.cs$' \
-        | grep -v 'Designer\|ModelSnapshot'
-      STOP
-    elif [ "$NEW_MIGRATIONS" -eq 1 ]; then
-      echo "✓ Single migration detected (squashed)"
-    else
-      echo "✓ No migrations in this feature"
-    fi
-  fi
-fi
-```
+See [references/pr-build-checks.md](../references/pr-build-checks.md) for:
+- Multi-runtime detection (.NET, npm, Python)
+- Build validation per runtime
+- Migration squash enforcement (feature branches: max 1 migration)
 
 ### 5. Generate PR Content
 
-**Title:**
-```bash
-BRANCH_NAME=$(echo $CURRENT | sed 's/.*\///')
-BRANCH_TYPE=$(echo $CURRENT | cut -d'/' -f1)
-
-case "$BRANCH_TYPE" in
-  feature) TITLE="feat: $BRANCH_NAME" ;;
-  hotfix)  TITLE="fix: $BRANCH_NAME" ;;
-  release) TITLE="release: v$GF_VERSION" ;;
-esac
-```
-
-**Body:**
-```markdown
-## Summary
-
-{Auto-generated from commit messages}
-
-## Changes
-
-{List of files changed with categories}
-
-## Testing
-
-- [ ] Build passes
-- [ ] Unit tests pass
-- [ ] Manual testing completed
-
-## EF Core Migrations
-
-{Migration status: None | Added | Modified}
-
----
-
-🤖 Generated with [Claude Code](https://claude.ai/code)
-```
+See [references/pr-generation.md](../references/pr-generation.md) for:
+- PR title generation (feat/fix/release format)
+- PR body template with summary, changes, testing, migrations
 
 ### 6. Create Pull Request
 
@@ -228,33 +143,12 @@ PR_ID=$(az repos pr list --source-branch "$CURRENT" --query "[0].pullRequestId"
 
 ### 7. Add Labels (GitHub)
 
-```bash
-if [ "$GIT_PROVIDER" = "github" ]; then
-  case "$BRANCH_TYPE" in
-    feature) gh pr edit $PR_NUMBER --add-label "enhancement" ;;
-    hotfix)  gh pr edit $PR_NUMBER --add-label "bug,priority" ;;
-    release) gh pr edit $PR_NUMBER --add-label "release" ;;
-  esac
-fi
-```
+Auto-label PRs (enhancement/bug/priority/release) based on branch type.
 
 ### 8. Store PR Info
 
-```bash
-# Persist PR info for merge step (uses config path for portability)
-CONFIG_DIR=$(dirname "$GF_CONFIG_FILE")
-cat > "$CONFIG_DIR/cache/pr-state.json" << EOF
-{
-  "pr_number": "$PR_NUMBER",
-  "pr_url": "$PR_URL",
-  "source_branch": "$CURRENT",
-  "target_branch": "$TARGET_BRANCH",
-  "git_provider": "$GIT_PROVIDER",
-  "created_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-}
-EOF
-echo "✓ PR state saved to $CONFIG_DIR/cache/pr-state.json"
-```
+See [references/pr-generation.md](../references/pr-generation.md) for:
+- PR state persistence to cache for merge step
 
 ### 9. Summary
 

package/templates/skills/gitflow/steps/step-start.md

@@ -33,103 +33,29 @@ Create a new feature/release/hotfix branch with optional worktree setup.
 
 ### 1. Load Config and Analyze Context
 
-```bash
-# Load GitFlow config (sets GF_* variables)
-# See _shared.md → READ_GITFLOW_CONFIG for all variables
-read_gitflow_config || { echo "❌ Run /gitflow init first."; exit 1; }
-
-CURRENT_BRANCH=$(git branch --show-current)
-git fetch origin --quiet
-
-# Version from config
-VERSION="$GF_VERSION"
-LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
-
-# Develop ahead of main?
-DEVELOP_AHEAD=$(git rev-list --count origin/$GF_MAIN_BRANCH..origin/$GF_DEVELOP_BRANCH 2>/dev/null || echo "0")
-
-# Working directory status
-DIRTY=$(git status --porcelain | wc -l)
-```
-
-**Display:**
-```
-Current: {CURRENT_BRANCH} | Version: {VERSION} | Tag: {LAST_TAG}
-Develop → Main: {DEVELOP_AHEAD} commits {DEVELOP_AHEAD > 10 ? "(Release recommended)" : ""}
-```
+Load GitFlow config. Display current branch, version, tag, and dirty status.
 
 ### 2. Interactive Questions (if no args)
 
-**If branch_type missing:**
-```yaml
-AskUserQuestion:
-  header: "Type"
-  question: "What type of branch?"
-  options:
-    - label: "Feature"
-      description: "New feature from develop"
-    - label: "Release v{X.Y+1.0}"
-      description: "Prepare release from develop"
-    - label: "Hotfix"
-      description: "Urgent fix from main"
-```
-
-**If branch_name missing:**
-```yaml
-AskUserQuestion:
-  header: "Name"
-  question: "Branch name? (will be normalized to kebab-case)"
-  # Free text input
-```
+Ask for branch type (feature/release/hotfix) and name if not provided via args. Display suggested next version for releases.
 
 ### 3. Normalize and Validate
 
-```bash
-# Normalize name
-normalize_branch_name() {
-  echo "$1" | tr '[:upper:]' '[:lower:]' | \
-    sed 'y/àâäéèêëïîôùûüçœæ/aaaeeeeiioouucoa/' | \
-    sed "s/[ _']/-/g" | sed 's/[^a-z0-9-]//g' | \
-    sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-50
-}
-
-BRANCH_NAME=$(normalize_branch_name "$branch_name")
-FULL_BRANCH="${branch_type}/${BRANCH_NAME}"
-
-# Check if exists
-LOCAL_EXISTS=$(git branch --list "$FULL_BRANCH")
-REMOTE_EXISTS=$(git branch -r --list "origin/$FULL_BRANCH")
-
-[ -n "$LOCAL_EXISTS" ] || [ -n "$REMOTE_EXISTS" ] && {
-  echo "ERROR: Branch '$FULL_BRANCH' already exists"
-  # Options: Different name | Checkout existing | Delete and recreate
-}
-```
+See [references/start-branch-normalization.md](../references/start-branch-normalization.md) for:
+- Branch name normalization (kebab-case)
+- Branch existence validation
 
 ### 4. Determine Base Branch
 
-| Type | Base Branch | Target |
-|------|-------------|--------|
+| Type | Base | Target |
+|------|------|--------|
 | feature | develop | develop |
-| release | develop | main + develop |
-| hotfix | main | main + develop |
-
-```bash
-case "$branch_type" in
-  feature) BASE_BRANCH="develop"; TARGET="develop" ;;
-  release) BASE_BRANCH="develop"; TARGET="main" ;;
-  hotfix)  BASE_BRANCH="main"; TARGET="main" ;;
-esac
-```
+| release | develop | main |
+| hotfix | main | main |
 
 ### 5. Handle Dirty Working Directory
 
-```bash
-[ "$DIRTY" -gt 0 ] && {
-  echo "Working directory has uncommitted changes"
-  # Options: Stash | Commit | Continue anyway | Cancel
-}
-```
+Offer user to stash, commit, or continue if working directory has changes.
 
 ### 5b. EF Core Migration Pre-flight (Release/Hotfix only)
 
@@ -143,31 +69,12 @@ Expected format: `{context}_v{version}_{sequence}_{Description}` (e.g., `core_v2
 
 ### 6. Create Branch and Worktree
 
-**Read worktree mode from config (already loaded by read_gitflow_config):**
-```bash
-WORKTREE_MODE="$GF_WORKTREE_MODE"
-```
-
-**Mode: organized (uses absolute paths from config)**
-```bash
-case "$branch_type" in
-  feature) WORKTREE_PATH="$GF_FEATURES_PATH/$BRANCH_NAME" ;;
-  release) WORKTREE_PATH="$GF_RELEASES_PATH/v$VERSION" ;;
-  hotfix)  WORKTREE_PATH="$GF_HOTFIXES_PATH/$BRANCH_NAME" ;;
-esac
-
-mkdir -p "$(dirname $WORKTREE_PATH)"
-git worktree add -b "$FULL_BRANCH" "$WORKTREE_PATH" "origin/$BASE_BRANCH"
-
-# Fix cross-platform paths in worktree metadata (if created from different platform)
-repair_worktree_paths "$(git rev-parse --git-common-dir)"
-```
-
-**Mode: --no-worktree**
-```bash
-git checkout "$BASE_BRANCH" && git pull origin "$BASE_BRANCH"
-git checkout -b "$FULL_BRANCH"
-```
+See [references/start-worktree-creation.md](../references/start-worktree-creation.md) for:
+- Worktree path selection (organized mode)
+- Numbering rules (only 01-Main/02-Develop, no numbered feature/release/hotfix)
+- Cross-platform path repair
+- Worktree validation
+- No-worktree mode fallback
 
 ### 6b. Push Branch to Remote (AUTOMATIC)
 

package/templates/skills/gitflow/steps/step-sync.md

@@ -65,24 +65,7 @@ Sync Status: {CURRENT}
 
 ### 4. Push Local Commits
 
-```bash
-[ "$AHEAD" -gt 0 ] && {
-  echo "Pushing $AHEAD commit(s) to origin/$CURRENT..."
-  git push origin $CURRENT
-
-  # CRITICAL: Verify push and update tracking refs
-  git fetch origin $CURRENT:refs/remotes/origin/$CURRENT --force --quiet
-  LOCAL_SHA=$(git rev-parse HEAD)
-  REMOTE_SHA=$(git rev-parse origin/$CURRENT)
-  if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
-    echo "✅ Push verified - local/remote in sync"
-  else
-    echo "⚠️ Push verification FAILED - refs may be stale"
-    echo "  Local:  $LOCAL_SHA"
-    echo "  Remote: $REMOTE_SHA"
-  fi
-}
-```
+See [references/sync-push-verify.md](../references/sync-push-verify.md) for push with verification.
 
 ### 5. Pull Remote Commits
 
@@ -126,59 +109,13 @@ Sync Status: {CURRENT}
 }
 ```
 
-### 7. Handle Rebase Conflicts
-
-```bash
-# If rebase has conflicts
-if [ -d ".git/rebase-merge" ] || [ -d ".git/rebase-apply" ]; then
-  echo "⚠️ REBASE CONFLICT DETECTED"
-
-  CONFLICTS=$(git diff --name-only --diff-filter=U)
-  echo "Conflicting files:"
-  echo "$CONFLICTS"
-
-  # Check for migration conflicts
-  MIGRATION_CONFLICTS=$(echo "$CONFLICTS" | grep "Migrations/")
-  [ -n "$MIGRATION_CONFLICTS" ] && {
-    echo "⚠️ Migration conflicts detected!"
-    echo "Recommend: /efcore:rebase-snapshot"
-  }
-
-  # Options
-  AskUserQuestion:
-    header: "Conflict"
-    question: "How to handle conflicts?"
-    options:
-      - label: "Resolve manually"
-        description: "I'll fix conflicts and continue"
-      - label: "Abort rebase"
-        description: "Cancel and return to previous state"
-      - label: "Accept theirs (migrations)"
-        description: "Use base branch migrations, regenerate ours"
-fi
-```
+### 7-8. Handle Rebase Conflicts and Force Push
 
-### 8. Force Push After Rebase
+See [references/sync-rebase-conflicts.md](../references/sync-rebase-conflicts.md) for:
+- Conflict detection and migration conflict handling
+- User options (resolve, abort, accept theirs)
 
-```bash
-# After successful rebase
-if [ "$REBASED" = true ]; then
-  echo "Rebase complete. Force pushing..."
-  git push --force-with-lease origin $CURRENT
-
-  # CRITICAL: Verify push and update tracking refs
-  git fetch origin $CURRENT:refs/remotes/origin/$CURRENT --force --quiet
-  LOCAL_SHA=$(git rev-parse HEAD)
-  REMOTE_SHA=$(git rev-parse origin/$CURRENT)
-  if [ "$LOCAL_SHA" = "$REMOTE_SHA" ]; then
-    echo "✅ Force push verified - local/remote in sync"
-  else
-    echo "⚠️ Force push verification FAILED"
-    echo "  Local:  $LOCAL_SHA"
-    echo "  Remote: $REMOTE_SHA"
-  fi
-fi
-```
+See [references/sync-push-verify.md](../references/sync-push-verify.md) for force push with verification.
 
 ### 9. Summary
 

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

@@ -166,8 +166,14 @@ When the user invokes `/ralph-loop`, they are giving you the instruction to:
 | File | Loaded when |
 |------|-------------|
 | `references/category-rules.md` | Step-01 and compact loop (category ordering and dependency rules) |
+| `references/category-completeness.md` | Step-01 section 4b and step-04 section 1.7 (guardrail injection) |
 | `references/compact-loop.md` | Step-04 section 5 (module loop with /apex delegation) |
+| `references/init-resume-recovery.md` | Step-00 section 4 (resume mode and auto-recovery) |
+| `references/multi-module-queue.md` | Step-00 and step-01 section 0 (multi-module initialization) |
+| `references/module-transition.md` | Step-04 section 3b (multi-module advancement) |
+| `references/parallel-execution.md` | Step-02 section 3a (Agent Teams for multi-module) |
 | `references/section-splitting.md` | Step-01 section 4c when module has >4 entities + >1 section |
+| `references/task-transform-legacy.md` | Step-01 (legacy FORMAT A PRD transformation) |
 | `references/team-orchestration.md` | Step-00 when multi-module detected (2+ PRDs) |
 </step_files>
 

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

@@ -0,0 +1,185 @@
+# Category Completeness Check
+
+> **Reference for:** step-01-task.md section 4b and step-04-check.md section 1.7
+> **Purpose:** Ensure PRD contains tasks for ALL required categories before/during execution
+> **Frequency:** On load (step-01) and every iteration (step-04)
+
+---
+
+## The Problem
+
+**Test-v4-005 Failure Mode:**
+- PRD generated with only backend categories (domain, infrastructure, application, api, seedData)
+- Frontend and test categories were entirely absent
+- Result: 0 frontend pages, 0 tests generated across 3 modules
+- Root cause: No guardrail detection during load
+
+## The Solution: Required Categories
+
+**CRITICAL:** Every PRD MUST have tasks for these categories:
+
+```javascript
+const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+```
+
+> **Why seedData is required:**
+> - Without it: Navigation/Permissions are not seeded
+> - Result: Frontend/test tasks execute against empty database
+> - Guardrail must inject NavigationApplicationSeedData, ApplicationRolesSeedData, etc.
+
+---
+
+## Completeness Check Function
+
+```javascript
+function checkCategoryCompleteness(prd) {
+  const presentCategories = new Set(prd.tasks.map(t => t.category));
+  const REQUIRED_CATEGORIES = ['domain', 'infrastructure', 'application', 'api', 'seedData', 'frontend', 'test'];
+  const missingCategories = REQUIRED_CATEGORIES.filter(c => !presentCategories.has(c));
+
+  if (missingCategories.length === 0) {
+    return { missing: [], guardrailsNeeded: [] };
+  }
+
+  console.warn(`⚠ PRD MISSING CATEGORIES: ${missingCategories.join(', ')}`);
+
+  // Calculate max ID for new guardrails
+  let maxIdNum = Math.max(...prd.tasks.map(t => {
+    const num = parseInt(t.id.replace(/[^0-9]/g, ''), 10);
+    return isNaN(num) ? 0 : num;
+  }), 0);
+
+  const prefix = prd.tasks[0]?.id?.replace(/[0-9]+$/, '') || 'GUARD-';
+  const lastApiTask = prd.tasks.filter(t => t.category === 'api').pop()?.id;
+  const lastSeedDataTask = prd.tasks.filter(t => t.category === 'seedData').pop()?.id;
+
+  // Dependency chain: domain → infrastructure → application → api → seedData → frontend → test
+  // Frontend MUST depend on seedData (navigation/permissions must be seeded first)
+  const frontendDep = lastSeedDataTask || lastApiTask;
+
+  const guardrailTasks = [];
+
+  for (const cat of missingCategories) {
+    maxIdNum++;
+    const taskId = `${prefix}${String(maxIdNum).padStart(3, '0')}`;
+
+    // Determine dependencies based on category order
+    let deps;
+    if (cat === 'seedData') {
+      deps = [lastApiTask]; // seedData depends on API infrastructure
+    } else if (cat === 'frontend') {
+      deps = [frontendDep]; // frontend depends on seedData (navigation must be seeded)
+    } else if (cat === 'test') {
+      deps = [frontendDep]; // test depends on seedData too
+    } else {
+      deps = [];
+    }
+
+    const guardrailTask = {
+      id: taskId,
+      description: `[GUARDRAIL] Generate ${cat} layer for ${prd.project?.module || 'module'}`,
+      status: 'pending',
+      category: cat,
+      dependencies: deps,
+      acceptance_criteria: determineAcceptanceCriteria(cat),
+      started_at: null,
+      completed_at: null,
+      iteration: null,
+      commit_hash: null,
+      files_changed: [],
+      validation: null,
+      error: null
+    };
+
+    guardrailTasks.push(guardrailTask);
+  }
+
+  return { missing: missingCategories, guardrailsNeeded: guardrailTasks };
+}
+
+function determineAcceptanceCriteria(category) {
+  const criteria = {
+    domain: 'Entity classes created with required properties',
+    infrastructure: 'EF Core configs, migrations created, dotnet build passes',
+    application: 'Service classes implementing business logic',
+    api: 'REST controllers with [RequirePermission] attributes',
+    seedData: 'NavigationApplicationSeedData + ApplicationRolesSeedData + PermissionsSeedData created, IClientSeedDataProvider wired, startup test passes',
+    frontend: 'React pages created via MCP scaffold_api_client + scaffold_routes, wired to App.tsx, navigation seed data verified in DB',
+    test: 'Unit + Integration test projects created, scaffold_tests MCP called, dotnet test passes'
+  };
+  return criteria[category] || `${category} layer fully implemented per category-rules.md`;
+}
+```
+
+## Application in step-01
+
+```javascript
+// After loading prd.json or generating tasks
+const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
+
+if (guardrailsNeeded.length > 0) {
+  console.log(`PRD updated: ${prd.tasks.length} → ${prd.tasks.length + guardrailsNeeded.length} tasks (${guardrailsNeeded.length} guardrails added)`);
+  prd.tasks.push(...guardrailsNeeded);
+
+  // Update frontendDep for any frontend guardrail if seedData was just injected
+  if (missing.includes('seedData')) {
+    const seedDataGuard = guardrailsNeeded.find(t => t.category === 'seedData');
+    const frontendGuard = prd.tasks.find(t => t.category === 'frontend' && t.description.includes('[GUARDRAIL]'));
+    if (frontendGuard && seedDataGuard) {
+      frontendGuard.dependencies = [seedDataGuard.id];
+    }
+  }
+
+  writeJSON('.ralph/prd.json', prd);
+}
+```
+
+## Application in step-04 (every iteration)
+
+```javascript
+// RUNS EVERY ITERATION — not just once
+const { missing, guardrailsNeeded } = checkCategoryCompleteness(prd);
+
+if (guardrailsNeeded.length > 0) {
+  prd.tasks.push(...guardrailsNeeded);
+  writeJSON('.ralph/prd.json', prd);
+
+  const newPending = prd.tasks.filter(t => t.status === 'pending').length;
+  console.log(`PRD updated: +${guardrailsNeeded.length} guardrails, ${newPending} pending tasks`);
+}
+```
+
+## Artifact Verification
+
+After category check, verify artifacts actually exist for completed tasks:
+
+```javascript
+const completedCats = new Set(prd.tasks.filter(t => t.status === 'completed').map(t => t.category));
+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
+};
+
+for (const [cat, check] of Object.entries(artifactChecks)) {
+  if (completedCats.has(cat) && !check()) {
+    console.warn(`ARTIFACT MISSING: ${cat} tasks marked completed but no files found — resetting to pending`);
+    prd.tasks.filter(t => t.category === cat && t.status === 'completed')
+      .forEach(t => {
+        t.status = 'pending';
+        t.error = 'Artifacts missing — re-execute';
+        t.completed_at = null;
+      });
+    writeJSON('.ralph/prd.json', prd);
+  }
+}
+```
+
+---
+
+## Key Rules
+
+- **Inject EVERY iteration:** Not just once during load
+- **Frontend depends on seedData:** Not just API
+- **Check artifacts:** Mark tasks pending if files don't exist
+- **Never skip:** This is the blocker for "missing frontend/test" failures

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

@@ -196,7 +196,7 @@ writeJSON('.ralph/prd.json', prd);
 **INVOKE `/apex -d .ralph/prd.json`**
 
 Apex handles everything for the current module:
-- Reads PRD, extracts context (context_code, app_name, module_code, entities, sections)
+- Reads PRD, extracts context (app_name, module_code, entities, sections)
 - Executes ALL layers: domain → infrastructure → migration → application → api → seed data → frontend → tests
 - Runs full POST-CHECKs (50 checks from `references/post-checks.md`)
 - Commits per layer (atomic commits)