# Readiness Scoring Algorithm

> **Used by:** step-00-validate (section 4: Calculate Readiness Score)
> **Purpose:** Evaluate module readiness for handoff based on acceptance criteria from validation-checklist.md.

---

## Algorithm

For each module, evaluate all acceptance criteria (AC-01 to AC-17) from `references/acceptance-criteria.md`.

### Score Calculation

```javascript
const blockingACs = ['AC-01', 'AC-02', 'AC-03', 'AC-04', 'AC-05', 'AC-06', 'AC-07',
                     'AC-08', 'AC-09', 'AC-10', 'AC-11', 'AC-12', 'AC-13',
                     'AC-15', 'AC-16', 'AC-17'];  // 16 blocking
const nonBlockingACs = ['AC-14'];  // 1 non-blocking (warning only)

// Count passes
const blockingPassed = blockingACs.filter(ac => results[ac] === 'PASS').length;
const blockingTotal = blockingACs.length;
const nonBlockingPassed = nonBlockingACs.filter(ac => results[ac] === 'PASS').length;
const nonBlockingTotal = nonBlockingACs.length;

// Scores
const blockingScore = (blockingPassed / blockingTotal) * 100;  // Must be 100%
const nonBlockingScore = (nonBlockingPassed / nonBlockingTotal) * 100;  // Warn if < 80%
```

### Gate Rules

| Condition | Action |
|-----------|--------|
| Blocking score = 100% | PASS — module ready for handoff |
| Blocking score < 100% | BLOCKING — list failed ACs, require fix |
| Non-blocking score >= 80% | OK — proceed normally |
| Non-blocking score < 80% | WARNING — suggest fixes but don't block |

---

## Output Format

### Per-Module Result

```javascript
{
  moduleCode: "Employees",
  blockingScore: 100,        // percentage
  blockingPassed: 16,
  blockingTotal: 16,
  nonBlockingScore: 100,
  nonBlockingPassed: 1,
  nonBlockingTotal: 1,
  ready: true,
  failedACs: [],             // empty if ready
  warnings: []               // non-blocking failures
}
```

### Readiness Table

```
┌──────────────┬──────────┬────────────┬──────────────┬────────┐
│ Module       │ Status   │ Blocking   │ Non-blocking │ Ready  │
├──────────────┼──────────┼────────────┼──────────────┼────────┤
│ Employees    │ consol.  │ 16/16 100% │ 1/1 100%     │ YES    │
│ Absences     │ consol.  │ 14/16  88% │ 1/1 100%     │ NO     │
└──────────────┴──────────┴────────────┴──────────────┴────────┘
```

### Failure Detail (when blocked)

```
Module "Absences" — 2 blocking ACs FAILED:

  FAIL AC-05: wireframes >= 1 = 0 (min: 1)
    Recovery: Re-run /business-analyse step-03 wireframe generation

  FAIL AC-09: seedDataCore 9 arrays = 7 (min: 9)
    Recovery: Re-run /business-analyse step-03 seedDataCore transform
```

---

## Recovery Actions

Each failed AC has a specific recovery action (from `references/acceptance-criteria.md`):

| AC | Recovery |
|----|----------|
| AC-01/02 | Re-run step-03 entity specification |
| AC-03/04 | Re-run step-03 use case / functional requirements |
| AC-05/06/07 | Re-run step-03 wireframe generation |
| AC-08 | Re-run step-03 section definition |
| AC-09 | Re-run step-03 seedDataCore transform |
| AC-10 | Auto-fix: wrap in array |
| AC-11 | Re-run step-03 API endpoints |
| AC-12 | Re-run step-03 messages |
| AC-13 | Re-run step-03 validations |
| AC-14 | Auto-fix: rename fields (non-blocking) |
| AC-15 | Auto-fix: wrap string in array |
| AC-16 | Auto-fix: copy description to message |
| AC-17 | Re-run step-03 gherkin |
