# BA Handoff Quality Gate

> **Used by:** step-01-task.md (section 1b)

## Purpose

Verify that the Business Analysis handoff is complete before generating tasks. A missing or incomplete handoff means no frontend files, no test plan, and no BR-to-code mapping — making full development impossible.

## When This Applies

This quality gate runs **ONLY** when BA artifacts are detected:

```javascript
const sourceFeatureJson = prd?.metadata?.sourceFeatureJson
  || findFile('docs/**/business-analyse/**/index.json')
  || findFile('docs/business/**/business-analyse/**/feature.json');  // legacy fallback
```

If `sourceFeatureJson` is null (manual start via `{task_description}`, no BA run), **skip this gate intentionally** — the loop proceeds in "manual mode" and generates tasks from the task description. This is by design, not a bug.

---

## Quality Gate Checks

### CHECK 1: Handoff Status

**Purpose:** Verify the BA phase completed and formally handed off.

```javascript
const feature = readJSON(sourceFeatureJson);
const handoff = feature.handoff || {};

if (handoff.status !== 'handed-off') {
  console.error(`BLOCKING: BA HANDOFF INCOMPLETE
handoff.status = "${handoff.status || 'missing'}" (expected "handed-off")
Run /business-analyse-handoff to generate the handoff, then re-run /business-analyse-develop.`);
  STOP;
}
```

**Error Message:**
```
BLOCKING: BA HANDOFF INCOMPLETE
handoff.status = "{actual}" (expected "handed-off")
Run /business-analyse-handoff to generate the handoff, then re-run /business-analyse-develop.
```

**Status Values:**
- `"handed-off"` — Handoff complete, safe to proceed
- `"in-progress"` — BA is still running
- `"not-started"` — No BA handoff created
- (missing) — No handoff object at all

---

### CHECK 2: Category Completeness

**Purpose:** Verify all required file categories have entries in filesToCreate.

```javascript
const filesToCreate = handoff.filesToCreate || {};
const requiredCategories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
const missingInHandoff = requiredCategories.filter(c => !filesToCreate[c] || filesToCreate[c].length === 0);

if (missingInHandoff.length > 0) {
  console.warn(`⚠ Handoff has empty categories: ${missingInHandoff.join(', ')}`);
}
```

**Warning Message:**
```
⚠ Handoff has empty categories: {list}
```

**Impact:** Non-blocking warning. The gate will display which categories are empty but does NOT stop execution. Subsequent checks (e.g., Category Completeness Check in section 4b) may inject guardrails for empty categories.

**Required Categories:**
1. `domain` — Entity definitions
2. `application` — Service/handler classes
3. `infrastructure` — EF configurations, DB migrations
4. `api` — Controllers, endpoints
5. `frontend` — Pages, components, screens
6. `seedData` — Navigation, permissions, roles, seed data
7. `tests` — Unit and integration tests
8. `documentation` — API docs, README, architecture docs

---

## Integration with Task Generation

**Before** generating any tasks from filesToCreate, ensure:
1. Handoff status is `"handed-off"` (CHECK 1)
2. All required categories are present or empty (CHECK 2, non-blocking)

**After** this gate passes:
- If filesToCreate exists and has entries → proceed to PRD v3 Transformation (section 2b)
- If filesToCreate is absent → proceed to task description analysis (section 2)

---

## Manual Mode (No BA Artifacts)

When `sourceFeatureJson` is null, the quality gate is **intentionally skipped**:

```javascript
if (!sourceFeatureJson) {
  console.log('Manual mode: no BA artifacts detected — tasks will be generated from task description');
  // Continue to section 2 (Analyze Task Description)
}
```

In manual mode:
- No handoff status check
- No filesToCreate validation
- Task breakdown generated from `{task_description}` (3-30 subtasks)
- **seedData is still MANDATORY** — generates navigation, permissions, roles

---

## Error Recovery

If CHECK 1 fails (handoff status not "handed-off"):

1. Run `/business-analyse-handoff` to complete BA
2. Verify `feature.handoff.status === "handed-off"`
3. Re-run `/business-analyse-develop`

If CHECK 2 warns about empty categories:

1. Review the missing categories
2. Optionally re-run BA to add files to those categories
3. Or accept the warning (subsequent guardrails will inject missing categories)
