@atlashub/smartstack-cli 4.41.0 → 4.43.0

package/templates/skills/{ba-design-ui → business-analyse-design}/steps/step-03-navigation.md

@@ -127,8 +127,15 @@ Write via ba-writer at project level (alongside master index.json). Update index
 | navigation.json | {project-path}/navigation.json    |
 
 NEXT STEPS:
-1. Run /ba-generate-html to produce the interactive HTML with mockups
+1. Run /business-analyse-html to produce the interactive HTML with mockups
 2. Client reviews the HTML (mockups, ERD, permission matrix)
-3. Run /ba-review to apply corrections
+3. Run /business-analyse-review to apply corrections
 ================================================================
 ```
+
+## Status Update
+
+After writing all screens and navigation, update the application status:
+```javascript
+ba-writer.updateStatus({feature_id}, "designed")
+```

package/templates/skills/business-analyse-develop/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: business-analyse-develop
+description: Autonomous development from PRD — implements the full application with MCP validation, quality gates, and completion guarantees.
+argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
+---
+
+<objective>
+Execute the Ralph Weegund technique — module orchestration with autonomous code generation. Ralph reads PRDs from `/business-analyse-handoff`, resolves dependencies, and delegates all code generation to `/apex -d`.
+
+**Key principle:** Ralph ORCHESTRATES (module sequencing, quality gates, reporting). All code generation is delegated to `/apex`.
+</objective>
+
+<quick_start>
+
+**From Business Analysis (RECOMMENDED):**
+```bash
+/business-analyse MyFeature
+# Then: /business-analyse-handoff
+# Then: /business-analyse-develop -r
+```
+
+**Manual start:**
+```bash
+/business-analyse-develop implement user authentication
+/business-analyse-develop -c "COMPLETE" -m 20 refactor cache layer
+/business-analyse-develop -r  # Resume previous
+```
+
+**Flags:** `-m N` (max iterations), `-c TEXT` (completion promise), `-v` (verbose), `-r` (resume), `-p` (parallel)
+
+</quick_start>
+
+<parameters>
+| Short | Long | Description |
+|-------|------|-------------|
+| `-m N` | `--max-iterations N` | Max iterations (default: 50, v4: adaptive) |
+| `-c TEXT` | `--completion-promise TEXT` | Completion signal text |
+| `-v` | `--verbose` | Detailed logging |
+| `-r` | `--resume` | Resume from previous state |
+| `-p` | `--parallel` | Teams mode: Phase 0 sequential, then parallel per module |
+</parameters>
+
+<prd_format_detection>
+
+## PRD Format Detection
+
+Ralph supports two PRD formats:
+
+| | PRD v3 (task-oriented) | PRD v4 (spec-oriented) |
+|---|---|---|
+| **Detection** | `$version === '3.0.0'` + `tasks[]` present | `$version === '4.0.0'` + `objectives[]` present |
+| **Execution model** | Batch iterations (compact-loop) | Continuous session (compaction manages context) |
+| **Context management** | Manual: "Read Once" rule, max 5 tasks/batch | Automatic: server-side compaction |
+| **Progress tracking** | progress.txt as state machine | Optional checkpoints |
+| **Splitting** | By token budget (>4 entities) | By logical feature (by section) |
+| **Steps** | 6 steps + compact-loop.md | 3 steps: init → execute → verify |
+
+**Backward compatibility:** v3 PRDs execute with the EXACT same behavior as before. v4 is opt-in via `/business-analyse-handoff --v4`.
+
+</prd_format_detection>
+
+<workflow>
+
+## v4 Workflow (spec-oriented — RECOMMENDED)
+
+**Single module:**
+1. **Init** (step-00): parse flags, verify MCP, load PRD v4, detect modules
+2. **Execute** (step-01-v4): delegate entire module to `/apex -d` as one continuous session
+   - `/apex` reads the spec (architecture, objectives, acceptance criteria)
+   - `/apex` decides execution order (domain → infra → app → api → seed → frontend → tests)
+   - Ralph intercepts at natural checkpoints for quality gates
+   - Server-side compaction manages context automatically
+3. **Verify + Report** (step-02-v4): run ALL quality gates, generate report
+
+**Multi-module:**
+1. Init: detect prd-*.json files, build topological order
+2. For each module in order → Execute (continuous session per module)
+3. Cross-module verify + final report
+
+**Quality gates (same as v3):**
+- `dotnet build` (BLOCKING)
+- `dotnet test` (BLOCKING after build)
+- `npm test` / `npm run typecheck` (BLOCKING for frontend)
+- MCP `validate_security` + `validate_conventions`
+- BR coverage check (each BR has implementation)
+- File reconciliation (expectedFiles vs disk)
+- Stub test detection (reject empty tests)
+
+## v3 Workflow (task-oriented — LEGACY)
+
+**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, 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
+7. Report (step-05)
+
+**Multi-module with `-p` (parallel mode):**
+1. Init: detect prd-*.json, parse `-p` flag (step-00)
+2. **Phase 0 (Ralph sequential):** ALL entities from ALL modules via `/apex --foundation`
+3. **Phase 1-N (Teams parallel):** Spawn teammates per module
+4. Report with per-module aggregation (step-05)
+
+**Multi-module WITHOUT `-p` (sequential — legacy):**
+1. Init: detect prd-*.json, read dependency layers (step-00)
+2. Compact loop per module in topological order
+3. Report with per-module aggregation (step-05)
+
+</workflow>
+
+<state_variables>
+| Variable | Type | v3 | v4 | Description |
+|----------|------|----|----|-------------|
+| `{max_iterations}` | number | Yes | Adaptive | Max iterations |
+| `{current_iteration}` | number | Yes | No | Current iteration counter |
+| `{current_module}` | string | Yes | Yes | Current module being processed |
+| `{modules_queue}` | object | Yes | Yes | Module queue (multi-module) |
+| `{prd_version}` | '3.0.0' \| '4.0.0' | Yes | Yes | Detected PRD format |
+| `{section_split_mode}` | boolean | Yes | No | v3 only: section splitting active |
+| `{parallel_mode}` | boolean | Yes | Yes | Teams mode via `-p` |
+</state_variables>
+
+<mcp_requirements>
+**MANDATORY before any work:**
+1. `mcp__smartstack__validate_conventions` — verify connectivity
+2. `mcp__context7__resolve-library-id` — verify connectivity
+
+**During work:** All MCP tool calls are handled by `/apex` during delegation.
+</mcp_requirements>
+
+<execution_guarantee>
+
+## EXECUTION GUARANTEE — READ THIS FIRST
+
+**Ralph-loop executes ALL work from start to finish. No exceptions.**
+
+When the user invokes `/business-analyse-develop`, they are giving you the instruction to:
+1. Initialize (step-00)
+2. Execute ALL modules autonomously
+3. Run quality gates
+4. Generate the final report
+
+**You MUST NOT:**
+- Stop to "ask for confirmation"
+- Set `max_iterations = 1` or any reduced value
+- Ask the user to choose between supervised/autonomous mode
+- Wait for user input between modules
+- Delegate the loop to sub-agents (except team mode and /apex delegation)
+
+**The ONLY valid stop conditions are:**
+- ALL objectives met / ALL tasks completed (→ report)
+- `max_iterations` reached (v3 only)
+- Dead-end (all remaining blocked/failed after retries)
+- User Ctrl+C
+
+**If you stop for any other reason, you have VIOLATED this guarantee.**
+
+</execution_guarantee>
+
+<entry_point>
+**FIRST ACTION:** Load `steps/step-00-init.md` — then execute ALL steps through to completion without stopping.
+</entry_point>
+
+<step_files>
+
+### v4 Steps (spec-oriented)
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse args, verify MCP, detect format, init state |
+| 01-v4 | `steps/step-01-v4-execute.md` | Continuous execution: delegate to /apex, run gates |
+| 02-v4 | `steps/step-02-v4-verify.md` | Final gates, file reconciliation, BR coverage, report |
+
+### v3 Steps (task-oriented — legacy)
+| Step | File | Purpose |
+|------|------|---------|
+| 00 | `steps/step-00-init.md` | Parse args, verify MCP, init state |
+| 01 | `steps/step-01-task.md` | Load/create tasks from prd.json |
+| 02 | `steps/step-02-execute.md` | Delegate module to /apex -d |
+| 03 | `steps/step-03-commit.md` | Commit, update prd.json/progress.txt |
+| 04 | `steps/step-04-check.md` | Check completion, compact loop entry |
+| 05 | `steps/step-05-report.md` | Generate final report |
+
+**v3 "Read Once" rule:** Step files read once, compact-loop.md drives iterations 2+.
+**v4:** No "Read Once" rule needed — compaction manages context automatically.
+
+**Reference files (loaded conditionally):**
+| File | Loaded when |
+|------|-------------|
+| `references/compact-loop.md` | v3 only: Step-04 section 5 |
+| `references/section-splitting.md` | v3 only: >4 entities + >1 section |
+| `references/category-completeness.md` | v3: step-01/step-04; v4: step-02-v4 |
+| `references/init-resume-recovery.md` | Both: Step-00 section 4 (resume mode) |
+| `references/multi-module-queue.md` | Both: multi-module initialization |
+| `references/quality-gates.md` | v4: step-01-v4 and step-02-v4 |
+</step_files>
+
+<file_structure>
+```
+.ralph/
+├── prd.json              # v3: unified task list OR v4: spec document
+├── prd-{module}.json     # Per-module PRDs (from business-analyse-handoff)
+├── progress.txt          # v3: state machine; v4: optional checkpoints
+├── modules-queue.json    # Multi-module tracking
+├── logs/
+└── reports/
+    └── {feature}.md
+```
+</file_structure>
+
+<execution_rules>
+
+### NON-NEGOTIABLE — Autonomous Full Execution
+- **EXECUTE ALL WORK** — from first module to last, no user interaction
+- **NEVER ask the user** — no mode selection, no "shall I continue?"
+- **NEVER stop prematurely** — only valid stops listed in execution_guarantee
+- **VERIFY MCP FIRST** — never skip
+
+### Quality Gates (both v3 and v4)
+- **BUILD GATE** — `dotnet build` must pass (BLOCKING)
+- **BACKEND TEST GATE** — `dotnet test` must pass (BLOCKING)
+- **FRONTEND TEST GATE** — `npm test` / `npm run typecheck` (BLOCKING)
+- **STUB TEST DETECTION** — reject `Assert.True(true)` or empty test methods
+- **MCP SECURITY** — validate_security + validate_conventions
+- **BR COVERAGE** — every business rule has implementation + test
+- **FILE RECONCILIATION** — expectedFiles vs actual files on disk
+- **MIGRATION** — after EF configs, before tests
+
+### Error Recovery
+- **v3:** Failed tasks retry up to 3 times, context NOT enriched
+- **v4:** Failures handled in same session — Claude has full error context via compaction, retries naturally with different approach
+
+</execution_rules>
+
+<success_criteria>
+- All objectives met (v4) / all tasks completed (v3)
+- MCP validations pass (validate_security + validate_conventions)
+- All quality gates pass (build, test, BR coverage, file reconciliation)
+- Git commits atomic with commit_hash tracked
+- Tests pass (dotnet test + npm test)
+- Migrations created and applied
+- Seed data complete (navigation, permissions, roles via MCP)
+- Frontend in correct hierarchy (Context/App/Module)
+- Report generated in .ralph/reports/
+- Multi-module: all modules processed, cross-module report
+</success_criteria>

package/templates/skills/{ralph-loop → business-analyse-develop}/references/category-completeness.md

@@ -159,7 +159,7 @@ 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));
 
-// Read custom patterns from PRD metadata (set by ss derive-prd based on project structure)
+// Read custom patterns from PRD metadata (set by ss business-analyse-handoff based on project structure)
 const customPatterns = prd.metadata?.artifactPatterns || {};
 
 const artifactChecks = {

package/templates/skills/{ralph-loop → business-analyse-develop}/references/init-resume-recovery.md

@@ -31,7 +31,7 @@ if (prd.$version === '3.0.0') {
 } else if (prd.project && prd.requirements && !prd.$version) {
   // FORMAT A deprecated — warn but transform
   console.warn('⚠ DEPRECATED: FORMAT A prd.json detected during resume');
-  console.warn('Re-run `ss derive-prd` to generate v3 format');
+  console.warn('Re-run `ss business-analyse-handoff` to generate v3 format');
   // NOTE: Transformation happens in step-01, not here
   resumeValid = true;
 } else {
@@ -87,19 +87,19 @@ if (handoffStatus === 'handed-off') {
   // BA handoff completed — auto-derive PRDs
   console.log('BA artifacts detected without PRD — auto-recovering...');
 
-  // Call ss derive-prd to generate PRD files
-  // 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}`);
+  // Call ss business-analyse-handoff to generate PRD files
+  // Flag: --feature (path to feature.json) — matches ss business-analyse-handoff CLI convention
+  // See also: step-05c-ralph-readiness.md section 2 "Fix: ss business-analyse-handoff --feature {path} --output ..."
+  const result = exec(`ss business-analyse-handoff --feature ${masterFeature}`);
 
   if (result.exitCode !== 0) {
-    console.error('ss derive-prd failed — cannot auto-recover');
+    console.error('ss business-analyse-handoff failed — cannot auto-recover');
     STOP;
   }
 
   const newPrds = glob('.ralph/prd-*.json');
   if (newPrds.length === 0) {
-    console.error('ss derive-prd did not create any PRD files');
+    console.error('ss business-analyse-handoff did not create any PRD files');
     STOP;
   }
 
@@ -109,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 /derive-prd to generate the handoff, then retry /ralph-loop');
+  console.warn('Run /business-analyse-handoff to generate the handoff, then retry /business-analyse-develop');
   STOP;
 }
 ```

package/templates/skills/{ralph-loop → business-analyse-develop}/references/multi-module-queue.md

@@ -147,7 +147,7 @@ if (fileExists(queuePath)) {
     }
     // LEGACY: FORMAT A
     else if (modulePrd.project && modulePrd.requirements && !modulePrd.$version) {
-      console.warn('⚠ DEPRECATED: FORMAT A prd.json detected. Re-run `ss derive-prd` to generate v3 format.');
+      console.warn('⚠ DEPRECATED: FORMAT A prd.json detected. Re-run `ss business-analyse-handoff` to generate v3 format.');
       writeJSON(currentModule.prdFile, transformPrdJsonToRalphV2(modulePrd, currentModule.code));
     }
     // v2 legacy

package/templates/skills/business-analyse-develop/references/quality-gates.md

@@ -0,0 +1,70 @@
+# Quality Gates Reference (v4)
+
+> **Used by:** step-01-v4-execute.md and step-02-v4-verify.md
+
+## Gate Definitions
+
+| Gate | Command | Blocking | When |
+|------|---------|----------|------|
+| Backend build | `dotnet build --no-restore` | YES | After each module |
+| Backend tests | `dotnet test --no-build` | YES | After build passes |
+| Frontend typecheck | `npm run typecheck` | YES | After backend gates |
+| Frontend tests | `npm test -- --run` | YES | After typecheck |
+| MCP security | `validate_security` | YES | After all tests |
+| MCP code review | `review_code` | YES (if perm mismatch) | After security |
+| MCP conventions | `validate_conventions` | NO (report) | After code review |
+| MCP test conventions | `validate_test_conventions` | NO (report) | After conventions |
+| BR coverage | grep implementation | YES (100%) | After MCP gates |
+| File reconciliation | compare expectedFiles vs disk | YES | After BR coverage |
+| Stub test detection | grep stub patterns | YES | During test gate |
+
+## Stub Test Patterns (AUTO-REJECT)
+
+```
+Assert.True(true)
+Assert.Pass()
+[Fact] + empty body
+// TODO
+throw new NotImplementedException
+[Test] public void Test1() { }
+```
+
+If any pattern found in test files → gate FAILS.
+
+## Gate Failure Recovery (v4)
+
+In v4 mode, gate failures are handled IN THE SAME SESSION:
+
+1. Gate fails → error output captured
+2. Error shown to Claude (compaction preserves all prior context)
+3. `/apex -d "Fix: {error description}"` — Claude sees what it generated + the error
+4. Re-run gate
+5. Max 3 fix attempts per gate before marking as failed
+
+**Key difference from v3:** No context loss between retry attempts. Claude knows exactly what code it wrote and what went wrong.
+
+## Gate Execution Order
+
+```
+dotnet build
+    ↓ (pass)
+dotnet test
+    ↓ (pass)
+npm run typecheck
+    ↓ (pass)
+npm test
+    ↓ (pass)
+validate_security
+    ↓ (pass)
+validate_conventions
+    ↓ (report)
+review_code (semantic permission check)
+    ↓ (pass)
+validate_test_conventions
+    ↓ (report)
+BR coverage check
+    ↓ (100%)
+File reconciliation
+    ↓ (all present)
+MODULE COMPLETE
+```

package/templates/skills/{ralph-loop → business-analyse-develop}/references/task-transform-legacy.md

@@ -1,7 +1,7 @@
 # Task Transform: Legacy PrdJson → Ralph v2 (DEPRECATED)
 
 > Reference for step-01-task.md — fallback transformation for old FORMAT A PRDs (pre-v3.9.0).
-> New PRDs generated by `ss derive-prd` use unified v3 format (`$version: "3.0.0"`)
+> New PRDs generated by `ss business-analyse-handoff` use unified v3 format (`$version: "3.0.0"`)
 > with pre-computed tasks. The v3 fast path in sections 0 and 1 bypasses this entirely.
 > This function will be removed in a future release.
 

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

@@ -69,7 +69,7 @@ The loop runs autonomously until:
 
 If tests are slow (>30s in logs), display warning but **continue execution**:
 ```
-⚠ Slow tests detected. Consider disabling E2E during ralph-loop.
+⚠ Slow tests detected. Consider disabling E2E during business-analyse-develop.
 ```
 
 ## 4. Resume or Initialize
@@ -78,7 +78,7 @@ See `references/init-resume-recovery.md` for complete Resume Mode and Auto-Recov
 
 **Quick:**
 - If `-r` flag: restore state from .ralph/prd.json
-- Else if BA artifacts exist: auto-recover PRDs via `ss derive-prd`
+- Else if BA artifacts exist: auto-recover PRDs via `ss business-analyse-handoff`
 - Else: fresh start
 
 ---
@@ -147,14 +147,30 @@ PROJECT_PATH=$(pwd)
 }
 ```
 
+## 6b. Detect PRD Version
+
+```javascript
+const prdFile = readJSON('.ralph/prd.json') || readJSON(glob('.ralph/prd-*.json')[0]);
+const prd_version = prdFile?.$version || '3.0.0';
+
+if (prd_version === '4.0.0') {
+  // v4 spec-oriented: continuous execution, compaction manages context
+  // → Load step-01-v4-execute.md instead of step-01-task.md
+} else {
+  // v3 task-oriented: batch iterations, compact-loop
+  // → Load step-01-task.md (legacy)
+}
+```
+
 ## 7. Show Summary
 
 ```
 RALPH LOOP INITIALIZED
 Task: {task_description} | Max: {max_iterations} | Promise: {completion_promise}
-MCP: Ready | Branch: {branch} | Schema: v3.0.0
+MCP: Ready | Branch: {branch} | PRD: v{prd_version}
 {modules_queue ? `Modules: ${totalModules} (${module_codes.join(' → ')})` : 'Mode: single module'}
--> Loading tasks...
+{prd_version === '4.0.0' ? '→ v4 continuous mode (compaction-enabled)' : '→ v3 batch mode (compact-loop)'}
+-> Loading spec...
 ```
 
 **Proceed directly to step-01-task.md**

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

@@ -79,7 +79,8 @@ If `{currentPrdPath}` does not exist: continue to section 1b.
 
 ```javascript
 const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
-  || findFile('docs/business/**/business-analyse/**/feature.json');
+  || findFile('docs/**/business-analyse/**/index.json')
+  || findFile('docs/business/**/business-analyse/**/feature.json');  // legacy fallback
 
 if (!sourceFeatureJson) {
   // Manual mode: no BA artifacts found — skip quality gate
@@ -93,7 +94,7 @@ if (!sourceFeatureJson) {
   if (handoff.status !== 'handed-off') {
     console.error(`BLOCKING: BA HANDOFF INCOMPLETE
 handoff.status = "${handoff.status || 'missing'}" (expected "handed-off")
-Run /derive-prd to generate the handoff, then re-run /ralph-loop.`);
+Run /business-analyse-handoff to generate the handoff, then re-run /business-analyse-develop.`);
     STOP;
   }
 

package/templates/skills/business-analyse-develop/steps/step-01-v4-execute.md

@@ -0,0 +1,131 @@
+---
+name: step-01-v4-execute
+description: Continuous execution — delegate full module to /apex with quality gates
+model: opus
+next_step: steps/step-02-v4-verify.md
+---
+
+# Step 01-v4: Continuous Module Execution
+
+## YOUR TASK
+
+For each module in topological order, delegate the ENTIRE module implementation to `/apex -d` in a continuous session. Run quality gates at natural checkpoints. Let server-side compaction manage context.
+
+---
+
+## EXECUTION SEQUENCE
+
+### 1. For Each Module in Queue
+
+```
+FOR module in topologicalOrder(modules):
+  1. Build apex delegation command
+  2. Delegate to /apex -d
+  3. Run quality gates after delegation completes
+  4. If gates fail → /apex fixes in same session
+  5. Module complete → advance to next
+```
+
+### 2. Build Apex Delegation
+
+Pass the FULL spec to apex — objectives, architecture, gates:
+
+```
+/apex -d .ralph/prd-{moduleCode}.json
+```
+
+Apex receives the v4 PRD and works autonomously through:
+1. **Domain layer** — entities, value objects, enums
+2. **Infrastructure** — EF configurations, DbContext registration
+3. **Migration** — ONE migration per module
+4. **Application** — services, DTOs, validators (implement ALL business rules)
+5. **API** — controllers with correct permissions
+6. **Seed data** — core (navigation, permissions, roles) + business
+7. **Frontend** — pages via `/ui-components`, routes, translations
+8. **Tests** — unit + integration via `scaffold_tests` (backend) + `scaffold_frontend_tests` (frontend). NO stubs, NO `Assert.True(true)`
+
+> Apex decides the order and approach. Ralph does NOT micro-manage.
+
+### 3. Quality Gates (Run After Apex Completes)
+
+After `/apex -d` returns, run ALL gates:
+
+```bash
+# Gate 1: Backend build (BLOCKING)
+dotnet build --no-restore 2>&1
+
+# Gate 2: Backend tests (BLOCKING)
+dotnet test --no-build 2>&1
+
+# Gate 3: Frontend checks (BLOCKING if frontend exists)
+npm run typecheck 2>&1
+npm test -- --run 2>&1
+```
+
+**If any gate fails:**
+1. DO NOT advance to next module
+2. Show the error to Claude (same conversation — compaction preserves context)
+3. Ask `/apex -d` to fix: `/apex -d "Fix build/test failures for module {moduleCode}"`
+4. Re-run gates
+5. Repeat until ALL gates pass (max 3 fix attempts per gate)
+
+### 4. MCP Validation Gates
+
+After build/test pass:
+
+```javascript
+// Security validation
+mcp__smartstack__validate_security({ projectPath: "." })
+
+// Convention validation
+mcp__smartstack__validate_conventions({ projectPath: "." })
+
+// Code review (semantic permission check)
+mcp__smartstack__review_code({ files: changedFiles, focus: "security" })
+```
+
+**Semantic permission check:** Verify that write endpoints (POST/PUT/DELETE) do NOT use Read-only permissions. Fix if found.
+
+### 5. BR Coverage Check
+
+For each business rule in `prd.brToCodeMapping`:
+1. Verify the target file exists on disk
+2. Grep for the rule implementation (method name or comment reference)
+3. If missing → delegate fix to apex: "Implement BR {ruleId} in {targetFile}"
+
+### 6. Stub Test Detection
+
+Grep test files for stub patterns:
+```bash
+grep -rn "Assert.True(true)\|Assert.Pass()\|// TODO\|throw new NotImplementedException" tests/ 2>/dev/null
+```
+
+If found → delegate fix to apex: "Replace stub tests with real implementations"
+
+### 7. Module Complete
+
+When ALL gates pass for a module:
+1. Log checkpoint: `"Module {moduleCode}: ALL GATES PASS"`
+2. Optionally append to progress.txt (human checkpoint)
+3. Advance to next module in queue
+
+---
+
+## ERROR RECOVERY (v4)
+
+Unlike v3 (retry counter + re-delegation), v4 leverages compaction:
+
+| Scenario | v3 behavior | v4 behavior |
+|----------|-------------|-------------|
+| Build fails | Inject fix task, re-iterate | Same session: Claude sees the error, fixes, re-builds |
+| Test fails | Inject fix task, re-iterate | Same session: Claude reads failure, adjusts code, re-tests |
+| MCP rejects | Mark task failed, retry 3x | Same session: Claude reads rejection reason, corrects |
+| Apex crashes | State lost between batches | Compaction preserves context, resume from last point |
+
+**Key advantage:** Claude has FULL context of what it just generated + the exact error. No context loss between retry attempts.
+
+---
+
+## NEXT STEP
+
+After ALL modules complete → Load: `steps/step-02-v4-verify.md`