---
name: step-04-validate
description: Self-check - run tests, verify AC, audit implementation quality
prev_step: steps/step-03-execute.md
next_step: steps/step-05-examine.md
---

# Step 4: Validate (Self-Check)

## MANDATORY EXECUTION RULES:

- NEVER claim checks pass when they don't
- NEVER skip any validation step
- ALWAYS run typecheck, lint, and tests
- ALWAYS verify each acceptance criterion
- ALWAYS fix failures before proceeding
- YOU ARE A VALIDATOR, not an implementer
- FORBIDDEN to proceed with failing checks

## YOUR TASK:

Validate the implementation by running checks, verifying acceptance criteria, and ensuring quality.

---

<available_state>
From previous steps:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What was implemented |
| `{task_id}` | Kebab-case identifier |
| `{acceptance_criteria}` | Success criteria |
| `{auto_mode}` | Skip confirmations |
| `{save_mode}` | Save outputs to files |
| `{test_mode}` | Include test steps |
| `{examine_mode}` | Auto-proceed to review |
| `{doc_mode}` | Documentation sync enabled |
| `{output_dir}` | Path to output (if save_mode) |
| Implementation | Completed in step-03 |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Discover Available Commands

Check `package.json` for exact command names:
```bash
cat package.json | grep -A 20 '"scripts"'
```

Look for: `typecheck`, `lint`, `test`, `build`, `format`

### 2. Run Validation Suite

**2.1 Typecheck**
```bash
pnpm run typecheck  # or npm run typecheck
```

**MUST PASS.** If fails:
1. Read error messages
2. Fix type issues
3. Re-run until passing

**2.2 Lint**
```bash
pnpm run lint
```

**MUST PASS.** If fails:
1. Try auto-fix: `pnpm run lint --fix`
2. Manually fix remaining
3. Re-run until passing

**2.3 Tests**
```bash
pnpm run test
```

**MUST PASS.** If fails:
1. Identify failing test
2. Determine if code bug or test bug
3. Fix the root cause
4. Re-run until passing

### 3. SmartStack Convention Validation (if MCP available)

**Use MCP to validate SmartStack conventions:**

```
mcp__smartstack__validate_conventions:
  checks: ["all"]
  # Valide: tables, migrations, services, namespaces, entities, tenants, controllers
```

**If EF Core changes detected, also run:**

```
mcp__smartstack__check_migrations:
  # Vérifie conflits, ordre chronologique, ModelSnapshot
```

**MCP validation checks:**
- [ ] Table naming (domain prefixes: auth_, nav_, cfg_, etc.)
- [ ] Migration naming ({context}_v{version}_{sequence}_{Description})
- [ ] Service interfaces (I*Service pattern)
- [ ] Namespace structure (Domain → Application → Infrastructure → API)
- [ ] Entity conventions (base classes, soft delete, audit)
- [ ] Tenant isolation (ITenantEntity where required)
- [ ] Controller routes (NavRoute attributes)

### 3b. Documentation Impact Check (informative)

**If `{doc_mode}` = true:**

Check if `docs-manifest.json` exists in the project root. If it does:

1. Read `docs-manifest.json`
2. Compare modified files (from step-03 todos) against `codeFiles` in manifest
3. For each impacted module, note:
   - Module name and featureId
   - Last documentation update date
   - Which code-to-doc mapping applies (entity → businessRules, controller → apiEndpoints, etc.)

**Report (informative only, does not block validation):**

```
Documentation Impact:
- Module: {app}/{module} (FEAT-NNN) — last doc update: {date}
  - Entity changes → businessRules, features may need update
  - Controller changes → apiEndpoints need update
```

**If `docs-manifest.json` absent:** Skip silently.

> **Note:** Actual documentation sync happens in step-04b-doc-sync.md (next step if doc_mode enabled).

### 4. Self-Audit Checklist

Verify each item:

**Tasks Complete:**
- [ ] All todos from step-03 marked complete
- [ ] No tasks skipped without reason
- [ ] Any blocked tasks have explanation

**Tests Passing:**
- [ ] All existing tests pass
- [ ] New tests written for new functionality
- [ ] No skipped tests without reason

**Acceptance Criteria:**
- [ ] Each AC demonstrably met
- [ ] Can explain how implementation satisfies AC
- [ ] Edge cases considered

**Patterns Followed:**
- [ ] Code follows existing patterns
- [ ] Error handling consistent
- [ ] Naming conventions match

### 5. Format Code

If format command available:
```bash
pnpm run format
```

### 6. Final Verification

Re-run all checks:
```bash
pnpm run typecheck && pnpm run lint
```

Both MUST pass.

### 7. Present Validation Results

```
**Validation Complete**

**Typecheck:** Pass
**Lint:** Pass
**Tests:** {X}/{X} passing
**Format:** Applied

**Acceptance Criteria:**
- [x] AC1: Verified by [how]
- [x] AC2: Verified by [how]

**Files Modified:** {list}

**Summary:** All checks passing, ready for next step.
```

### 8. Save Output (if save_mode)

**If `{save_mode}` = true:**

Write to `{output_dir}/04-validate.md`:
- Validation results
- AC verification
- Timestamp
- Update 00-context.md Progress table: 04-validate -> Complete

### 9. Determine Next Step

**Decision tree:**

```
IF {doc_mode} = true AND docs-manifest.json exists:
    -> Load step-04b-doc-sync.md (documentation sync)

ELSE IF {test_mode} = true:
    -> Load step-07-tests.md (test analysis and creation)

ELSE IF {examine_mode} = true:
    -> Load step-05-examine.md (adversarial review)

ELSE IF {auto_mode} = false:
    -> Ask user what to do next

ELSE:
    -> Complete workflow (show final summary)
```

**If `{auto_mode}` = false:**

```yaml
questions:
  - header: "Next"
    question: "Validation complete. What would you like to do?"
    options:
      - label: "Run adversarial review"
        description: "Deep review for security, logic, and quality"
      - label: "Complete workflow"
        description: "Skip review and finalize"
      - label: "Add tests"
        description: "Create additional tests first"
    multiSelect: false
```

---

## SUCCESS METRICS:

- Typecheck passes
- Lint passes
- All tests pass
- All AC verified
- Code formatted
- User informed of status

## FAILURE MODES:

- Claiming checks pass when they don't
- Not running all validation commands
- Skipping tests for modified code
- Missing AC verification
- Proceeding with failures

---

## NEXT STEP:

Based on flags (check in order):
- **If test_mode:** Load `./step-07-tests.md`
- **If examine_mode OR user requests:** Load `./step-05-examine.md`
- **Otherwise:** Workflow complete - show summary
