# Handoff Global Validation

## Overview

POST-CHECK GLOBAL validation (BLOCKING — ba-009 fix). Verifies overall handoff integrity across all modules, not just individual PRDs.

Blocks completion if expected files are missing.

## Module-Level Integrity Checks

For each module:

### handoff.json Presence (CRITICAL)

Check that handoff.json exists in module's docs directory.

This file was missing for 3/12 modules in ba-009 and is critical for handoff integrity.

```javascript
if (!EXISTS(moduleDir + '/handoff.json'))
  errors.push('MISSING: ' + moduleDir + '/handoff.json');
```

### PRD Master File

Check that main PRD file exists in .ralph/ directory.

```javascript
if (!EXISTS('.ralph/prd-' + mod.code + '.json'))
  errors.push('MISSING: .ralph/prd-' + mod.code + '.json');
```

### Companion Files

Check that all 5 companion specification files exist in .ralph/:
- entities
- rules
- usecases
- screens
- permissions

```javascript
['entities', 'rules', 'usecases', 'screens', 'permissions'].forEach(suffix => {
  const path = '.ralph/prd-' + mod.code + '.' + suffix + '.json';
  if (!EXISTS(path)) errors.push('MISSING: ' + path);
});
```

## Global File Checks

### Multi-Module Queue

If processing 2+ modules, check that modules-queue.json exists.

```javascript
if (modules.length >= 2 && !EXISTS('.ralph/modules-queue.json'))
  errors.push('MISSING: .ralph/modules-queue.json');
```

### Progress Tracker

Check that progress.txt exists.

```javascript
if (!EXISTS('.ralph/progress.txt'))
  errors.push('MISSING: .ralph/progress.txt');
```

## Surplus File Detection

Check for unexpected files in .ralph/ that aren't part of the template.

### Expected Files Set

Build set of all expected files:
- PRD masters: `prd-{moduleCode}.json` for each module
- Companion files: `prd-{moduleCode}.{suffix}.json` for each module and suffix
- Global files: `modules-queue.json`, `progress.txt`

```javascript
const expectedFiles = new Set();
modules.forEach(m => {
  expectedFiles.add('prd-' + m.code + '.json');
  ['entities','rules','usecases','screens','permissions'].forEach(s =>
    expectedFiles.add('prd-' + m.code + '.' + s + '.json'));
});
expectedFiles.add('modules-queue.json');
expectedFiles.add('progress.txt');
```

### Actual Files in .ralph/

Scan .ralph/ directory for all files (excluding logs/).

Flag any file not in expected set as surplus with warning message.

```javascript
const actualFiles = GLOB('.ralph/*').filter(f => !f.includes('/logs/'));
actualFiles.forEach(f => {
  const basename = f.split('/').pop();
  if (!expectedFiles.has(basename))
    warnings.push('SURPLUS: ' + f + ' — fichier non prevu par le template');
});
```

## Result Handling

### Blocking Errors

If errors exist, display all errors and block completion.

```javascript
if (errors.length > 0) {
  Display('POST-CHECK GLOBAL FAILED (' + errors.length + ' errors):');
  errors.forEach(e => Display('  X ' + e));
  BLOCKING_ERROR('Fix all missing files before completing. See FICHIERS A CREER in step-01.');
}
```

### Warnings

Display any surplus files found (non-blocking).

```javascript
if (warnings.length > 0) {
  Display('POST-CHECK warnings (' + warnings.length + ' surplus files):');
  warnings.forEach(w => Display('  ! ' + w));
}
```

### Success Message

Display final validation pass message with module count and expected file count.

```javascript
Display('POST-CHECK GLOBAL PASS: ' + modules.length + ' modules, ' +
  (modules.length * 7 + 2) + ' fichiers attendus');
```

Formula: `modules.length * 7 + 2`
- Each module: 1 PRD master + 5 companions + 1 handoff.json = 7 files
- Global: modules-queue.json (if multi-module) + progress.txt = 2 files
