@atlashub/smartstack-cli 4.74.0 → 4.75.0

package/templates/skills/business-analyse-handoff/references/handoff-global-validation.md

@@ -0,0 +1,142 @@
+# 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

package/templates/skills/business-analyse-handoff/references/prd-validation-checks.md

@@ -0,0 +1,125 @@
+# PRD Validation Checks
+
+## Overview
+
+POST-CHECK PRD validation rules (BLOCKING). All checks must pass before proceeding to development.
+
+## Check 1: Version
+
+PRD $version must be 3.0.0 or 4.0.0.
+
+```javascript
+if (prd.$version !== "3.0.0" && prd.$version !== "4.0.0") {
+  BLOCKING_ERROR("PRD version must be 3.0.0 or 4.0.0, got: " + prd.$version);
+}
+```
+
+## Check 2: File Manifest Location
+
+PRD must contain file manifest in correct location:
+- v3: `implementation.filesToCreate`
+- v4: `expectedFiles`
+
+```javascript
+const ftc = prd.$version === "4.0.0" ? prd.expectedFiles : prd.implementation?.filesToCreate;
+if (!ftc) {
+  BLOCKING_ERROR("prd.json missing file manifest (v3: implementation.filesToCreate, v4: expectedFiles)");
+  STOP;
+}
+```
+
+## Check 3: All 8 Categories Present
+
+File manifest must contain all 8 categories:
+- domain
+- application
+- infrastructure
+- api
+- frontend
+- seedData
+- tests
+- documentation
+
+```javascript
+const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
+const missingCategories = categories.filter(cat => !ftc[cat]);
+if (missingCategories.length > 0) {
+  BLOCKING_ERROR("Missing categories: " + missingCategories.join(', '));
+}
+```
+
+## Check 4: File Counts Match
+
+File count for each category must match between PRD and feature handoff.
+
+```javascript
+for (const cat of categories) {
+  const prdCount = ftc[cat]?.length ?? 0;
+  const featureCount = featureHandoff[cat]?.length ?? 0;
+  if (prdCount !== featureCount) {
+    BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
+  }
+}
+```
+
+## Check 5: Specification Files (Companion Files)
+
+PRD must contain all 5 companion file definitions:
+- entities
+- rules
+- usecases
+- screens
+- permissions
+
+Each companion file must exist and be non-empty (>10 bytes).
+
+```javascript
+const specFiles = prd.specificationFiles;
+if (!specFiles) {
+  BLOCKING_ERROR("specificationFiles missing from PRD");
+}
+const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
+for (const key of specKeys) {
+  if (!specFiles[key]) {
+    BLOCKING_ERROR(`specificationFiles.${key} path missing`);
+  }
+  const companionPath = `.ralph/${specFiles[key]}`;
+  if (!fileExists(companionPath)) {
+    BLOCKING_ERROR(`Companion file not found: ${companionPath}`);
+  }
+  const companionSize = fileSize(companionPath);
+  if (companionSize < 10) {
+    BLOCKING_ERROR(`Companion file empty or too small: ${companionPath} (${companionSize} bytes)`);
+  }
+}
+```
+
+## Check 6: C# Identifier Validity
+
+File paths must be valid C# identifiers (no spaces, apostrophes, accents).
+
+Error message pattern:
+```
+File path contains illegal characters for C# identifier: "{filePath}"
+— entity name must be canonicalized (see references/entity-canonicalization.md)
+```
+
+Implementation:
+
+```javascript
+for (const [cat, files] of Object.entries(ftc)) {
+  for (const file of (files || [])) {
+    const filePath = file.path || file;
+    // Extract filename without extension
+    const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
+    // Check for illegal characters in C# file names
+    if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
+      BLOCKING_ERROR(`${cat}: File path contains illegal characters for C# identifier: "${filePath}" — entity name must be canonicalized (see references/entity-canonicalization.md)`);
+    }
+  }
+}
+```
+
+## Display Output
+
+Display verification table showing all 8 categories match between module JSON files and prd.json.

package/templates/skills/business-analyse-handoff/references/project-index-update.md

@@ -0,0 +1,98 @@
+# Project Index Update
+
+## Overview
+
+Updates the project index with handoff status tracking after PRD generation.
+
+Two-tier approach:
+- **Primary (ba-006):** Project-level index in `{docs_dir}/index.json` (autonomous per project)
+- **Legacy (pre-ba-006):** Global manifest in `docs/index.json` for backward compatibility
+
+## Primary Flow: Update Project-Level Index
+
+For each processed module, update the project's own `{docs_dir}/index.json` manifest.
+
+### Update Logic
+
+1. Read `{docs_dir}/index.json` (project master index)
+2. Update status to `"handed-off"` for each processed module
+3. Update `metadata.lastModified` timestamp
+4. Write back to `{docs_dir}/index.json`
+5. Display confirmation: "Project index updated: {docs_dir}/index.json (status: handed-off)"
+
+## Legacy Flow: Update Global Manifest (if exists)
+
+For backward compatibility with pre-ba-006 projects, if `docs/index.json` global manifest exists, also update it.
+
+### Structure
+
+```json
+{
+  "version": "1.0",
+  "updatedAt": "{ISO timestamp}",
+  "analyses": [
+    {
+      "appCode": "{app_code}",
+      "appName": "{application_name}",
+      "moduleCode": null | "{module_code}",
+      "moduleName": "{module_name}",
+      "version": "{version}",
+      "status": "handed-off",
+      "featureDescription": "{description}",
+      "path": "{projectSlug}/v{version}/index.json",
+      "updatedAt": "{ISO timestamp}"
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Notes |
+|-------|-------|
+| `appCode` | Application identifier |
+| `appName` | Human-readable application name |
+| `moduleCode` | Module identifier (null if global module) |
+| `moduleName` | Module name |
+| `version` | Feature/module version |
+| `status` | Always "handed-off" after update |
+| `featureDescription` | Module description from BA |
+| `path` | Reference path (format: `{projectSlug}/v{version}/index.json`) |
+| `updatedAt` | ISO timestamp of last update |
+
+### Update Steps
+
+1. Read existing `docs/index.json` if present
+2. For each module, add or update entry in `analyses` array
+3. Set `status: "handed-off"`
+4. Update global `updatedAt` timestamp
+5. Write back to `docs/index.json`
+6. Display confirmation: "Legacy index updated: docs/index.json"
+
+## Execution Order
+
+```
+1. Update {docs_dir}/index.json (primary)
+   └─ Always execute for ba-006+
+
+2. IF docs/index.json exists
+   └─ Update with legacy structure (backward compat)
+```
+
+## Display Messages
+
+### Primary Update
+```
+Project index updated: {docs_dir}/index.json (status: handed-off)
+```
+
+### Legacy Update (if applicable)
+```
+Legacy index updated: docs/index.json ({count} modules)
+```
+
+## Key Notes
+
+- **ba-006 Standard:** Projects are autonomous — no global manifest required
+- **Backward Compatibility:** Legacy projects using global `docs/index.json` continue to work
+- **No Global Dependency:** CLI does not maintain a global registry; each project is self-contained

package/templates/skills/business-analyse-handoff/steps/step-01-transform.md

@@ -21,6 +21,12 @@ next_step: steps/step-02-export.md
 - **ALWAYS** generate API endpoints from use cases + entities (BA does not produce apiEndpoints)
 - **ALWAYS** canonicalize entity names before generating file paths — see `references/entity-canonicalization.md`
 
+## FICHIERS A CREER — LISTE FERMEE (ba-009 fix)
+
+> **Load** `references/handoff-file-inventory.md` for exhaustive file list, naming regex, and forbidden variants.
+
+---
+
 ## YOUR TASK
 
 Orchestrate the transform: determine module order, then delegate each module's transform to an Agent with isolated context. This prevents context accumulation across modules.
@@ -29,16 +35,7 @@ Orchestrate the transform: determine module order, then delegate each module's t
 
 ## CONTEXT ISOLATION ARCHITECTURE
 
-```
-Main conversation (orchestrator):
-  ├─ Determine topological order
-  ├─ FOR each module:
-  │   └─ Agent(ba-writer) ──► reads 5 files, builds handoff, writes result
-  │                           (isolated context: ~500-1000 lines per module)
-  └─ Collect results, display summary
-```
-
-**WHY:** A 10-module project has ~10K lines of JSON data. Loading all at once exceeds Sonnet's effective context. Processing one module per Agent keeps each invocation under ~2K lines.
+> **Load** `references/context-isolation-pattern.md` for the orchestration pattern, agent delegation flow, and context budget rules.
 
 ---
 
@@ -57,157 +54,9 @@ Module processing order:
 
 ### 2. Process Each Module via Agent
 
-For **EACH module** in topological order, use the **Agent tool** (subagent_type: `ba-writer`) with the following prompt structure:
+For **EACH module** in topological order, use the **Agent tool** (subagent_type: `ba-writer`) with:
 
-```
-Transform module "{moduleCode}" for handoff.
-
-## Input
-- Module BA directory: {moduleDir}  // ba-006: {docs_dir}/{appKebab}/{moduleKebab}/
-- Application code: {appCode}
-- Application name: {appName}
-- Feature description: {featureDescription}
-- Module index: {moduleDir}/index.json
-
-## Instructions
-Read the following 5 files from {moduleDir} (ba-006: docs/{projectSlug}/v{X.Y}/{appKebab}/{moduleKebab}/):
-  1. entities.json → entities[]
-  2. usecases.json → useCases[] (canonical key: "useCases", fallback: "usecases")
-  3. rules.json → rules[] (canonical key: "rules", fallback: "businessRules")
-  4. permissions.json → roles[], matrix[], permissionPaths[]
-  5. screens.json → sections[] (canonical key: "sections", fallback: "screens")
-
-### Normalization Safety Net (BACKWARD COMPAT)
-When reading flat files, prefer canonical keys but fall back to alternatives:
-  - useCases: `data.useCases || data.usecases || []`
-  - primaryActor: `uc.primaryActor || uc.actor`
-  - mainScenario: `uc.mainScenario || uc.steps` (if steps[] contains objects, extract `.action`)
-  - rules: `data.rules || data.businessRules || []`
-  - screens: `data.sections || data.screens` (if screens[] exists, treat each screen as a section with 1 resource)
-This safety net handles pre-4.52 BA outputs. It should become unnecessary once step-03-specify enforces canonical keys.
-
-Then build the handoff data following these rules:
-
-### Complexity
-| Criteria | Simple | Medium | Complex |
-|----------|--------|--------|---------|
-| Entities | <=3 | <=6 | >6 |
-| Use Cases | <=5 | <=12 | >12 |
-| Business Rules | <=10 | <=20 | >20 |
-
-### API Endpoints (generate from use cases)
-- UC "Create X" → POST /api/{app}/{module}
-- UC "List X"   → GET  /api/{app}/{module}
-- UC "Update X" → PUT  /api/{app}/{module}/{id}
-- UC "Delete X" → DELETE /api/{app}/{module}/{id}
-- UC "Get X"    → GET  /api/{app}/{module}/{id}
-- Use permission paths from permissions.json
-
-### Section UC/BR Enrichment
-Using sectionCode from usecases.json and rules.json, link each UC and BR to its section.
-
-### Entity Name Canonicalization (MANDATORY)
-Before generating any file paths, canonicalize ALL entity names from `entities.json`:
-1. Read `references/entity-canonicalization.md` for complete rules
-2. For each entity in `entities.json > entities[]`:
-   - If entity has `codeIdentifier` or `englishName` → use it directly
-   - Otherwise → apply canonicalization: strip diacritics, remove apostrophes/spaces, remove French articles (d, de, du, l, la, le, les, un, une, des, a, au, aux, en), PascalCase
-3. Use the CANONICALIZED name in ALL file path templates (`{EntityName}`, `{ServiceName}`, `{DtoName}`, etc.)
-4. Store the mapping `{ originalName: "Type d'absence", canonicalName: "TypeAbsence" }` in handoff metadata for traceability
-
-**Example:** Entity `"Type d'absence"` → canonicalized to `"TypeAbsence"` → path `src/Domain/Entities/App/Module/TypeAbsence.cs`
-
-**BLOCKING:** If ANY entity name after canonicalization is not a valid C# identifier (`/^[A-Za-z_][A-Za-z0-9_]*$/`), STOP and report the error.
-
-### File Mapping (8 Categories)
-Read `references/handoff-file-templates.md` for complete JSON templates.
-All backend paths MUST include {ApplicationName}/ hierarchy.
-
-| Category | Source | Key rules |
-|----------|--------|-----------|
-| **Domain** | entities[] | Entities, ValueObjects, Enums |
-| **Application** | useCases[] | Services, DTOs, Validators |
-| **Infrastructure** | entities[] | EF Configurations, DbSet |
-| **API** | Generated from useCases + entities | Controllers |
-| **Frontend** | screens[] | Pages, Components, Hooks; split by file (NOT monolithic) |
-| **SeedData** | entities + permissions | CORE + business (include category field) |
-| **Tests** | All layers | Unit, Integration, Security |
-| **Documentation** | All layers | Technical docs (can be empty []) |
-
-Frontend: each page as separate entry, FK fields, ALL pages use /ui-components.
-Routes: PascalCase module codes → kebab-case (NEVER include /business/ prefix).
-
-### BR-to-Code Mapping
-Read `references/handoff-mappings.md` for mapping rules.
-For each rule: ruleId, title, module, severity, implementationPoints[].
-
-### personRoleConfig
-If entity has personRoleConfig, copy verbatim into handoff.
-
-### SeedData
-Read `references/handoff-seeddata-generation.md` for core seed generation.
-- category: "core" → Navigation, Permissions, Roles
-- category: "business" → Domain-specific data
-
-### Entity Domain Mapping
-Read `references/entity-domain-mapping.md` for mapping rules.
-- Entity → src/Domain/Entities/{App}/{Module}/{EntityName}.cs
-- ValueObject → src/Domain/{Module}/ValueObjects/{VOName}.cs
-- Enum → src/Domain/{Module}/Enums/{EnumName}.cs
-
-### Dependencies per File Entry
-| Layer | Dependencies |
-|-------|-------------|
-| domain | [] |
-| infrastructure | ["domain"] |
-| application | ["domain"] |
-| api | ["application"] |
-| seedData | ["domain", "infrastructure"] |
-| frontend | ["api"] |
-| tests | ["domain", "application", "infrastructure", "api"] |
-| documentation | [] |
-
-### Write Result
-Write via ba-writer.enrichModuleHandoff with the complete handoff payload:
-- complexity, filesToCreate (8 categories), brToCodeMapping, apiEndpointSummary
-- prdFile: ".ralph/prd-{moduleCode}.json"
-- totalFiles, totalTasks, handedOffAt (ISO timestamp)
-- featureDescription: {featureDescription}
-
-### Specification Files (MANDATORY)
-After writing the handoff data, ALSO write 5 companion files:
-1. `.ralph/prd-{moduleCode}.entities.json` = VERBATIM copy of `{moduleDir}/entities.json`
-2. `.ralph/prd-{moduleCode}.rules.json` = VERBATIM copy of `{moduleDir}/rules.json`
-3. `.ralph/prd-{moduleCode}.usecases.json` = VERBATIM copy of `{moduleDir}/usecases.json`
-4. `.ralph/prd-{moduleCode}.screens.json` = VERBATIM copy of `{moduleDir}/screens.json`
-5. `.ralph/prd-{moduleCode}.permissions.json` = VERBATIM copy of `{moduleDir}/permissions.json`
-
-Add `specificationFiles` to the PRD referencing these files (relative names, all in `.ralph/`):
-```json
-"specificationFiles": {
-  "entities": "prd-{moduleCode}.entities.json",
-  "rules": "prd-{moduleCode}.rules.json",
-  "usecases": "prd-{moduleCode}.usecases.json",
-  "screens": "prd-{moduleCode}.screens.json",
-  "permissions": "prd-{moduleCode}.permissions.json"
-}
-```
-
-### POST-CHECK (BLOCKING)
-After writing, verify:
-1. Handoff not empty
-2. All 8 categories present
-3. brToCodeMapping non-empty
-4. Section resources have entity field
-5. SeedData contains CORE entries (NavigationModuleSeedData, NavigationSectionSeedData if sections exist, PermissionsSeedData, RolesSeedData)
-6. For FIRST module only: SeedData contains APP-LEVEL CORE entries (NavigationApplicationSeedData, ApplicationRolesSeedData)
-7. All 5 companion files exist in `.ralph/` and are non-empty
-8. `specificationFiles` present in the PRD with all 5 paths
-9. Entity count in companion matches source: `prd-{moduleCode}.entities.json` entities[] count = `{moduleDir}/entities.json` entities[] count
-10. BR count in companion matches source: `prd-{moduleCode}.rules.json` rules[] count = `{moduleDir}/rules.json` rules[] count
-11. Each `brToCodeMapping[].statement` is non-empty (not just a title paraphrase)
-Display: "POST-CHECK PASS: {moduleCode} -- 8 categories, {brCount} BRs mapped, {coreCount} core seeds, 5 companion files"
-```
+> → **Load** `references/agent-handoff-transform-prompt.md` as the complete agent prompt for each module transformation.
 
 ### 3. Display Progress
 

package/templates/skills/business-analyse-handoff/steps/step-02-export.md

@@ -58,76 +58,9 @@ Generates `prd-{moduleCode}.json` with `$version: "4.0.0"` containing:
 
 ### 2. POST-CHECK PRD (BLOCKING)
 
-> **Reference:** See loaded context `prd-generation.md` for complete validation rules.
+> **Reference:** See loaded context `prd-validation-checks.md` for complete validation rules (6 checks: version, file manifest, categories, counts, companions, C# identifiers).
 
-```javascript
-const prd = readJSON(`.ralph/prd-${moduleCode}.json`);
-const featureHandoff = moduleFeature.handoff.filesToCreate;
-
-// Check 1: Version
-if (prd.$version !== "3.0.0" && prd.$version !== "4.0.0") {
-  BLOCKING_ERROR("PRD version must be 3.0.0 or 4.0.0, got: " + prd.$version);
-}
-
-// Check 2: filesToCreate location (v3: implementation.filesToCreate, v4: expectedFiles)
-const ftc = prd.$version === "4.0.0" ? prd.expectedFiles : prd.implementation?.filesToCreate;
-if (!ftc) {
-  BLOCKING_ERROR("prd.json missing file manifest (v3: implementation.filesToCreate, v4: expectedFiles)");
-  STOP;
-}
-
-// Check 3: All 8 categories present
-const categories = ['domain', 'application', 'infrastructure', 'api', 'frontend', 'seedData', 'tests', 'documentation'];
-const missingCategories = categories.filter(cat => !ftc[cat]);
-if (missingCategories.length > 0) {
-  BLOCKING_ERROR("Missing categories: " + missingCategories.join(', '));
-}
-
-// Check 4: File counts match
-for (const cat of categories) {
-  const prdCount = ftc[cat]?.length ?? 0;
-  const featureCount = featureHandoff[cat]?.length ?? 0;
-  if (prdCount !== featureCount) {
-    BLOCKING_ERROR(`${cat}: prd=${prdCount} but feature=${featureCount}`);
-  }
-}
-
-// Check 5: Specification files (companion files)
-const specFiles = prd.specificationFiles;
-if (!specFiles) {
-  BLOCKING_ERROR("specificationFiles missing from PRD");
-}
-const specKeys = ['entities', 'rules', 'usecases', 'screens', 'permissions'];
-for (const key of specKeys) {
-  if (!specFiles[key]) {
-    BLOCKING_ERROR(`specificationFiles.${key} path missing`);
-  }
-  const companionPath = `.ralph/${specFiles[key]}`;
-  if (!fileExists(companionPath)) {
-    BLOCKING_ERROR(`Companion file not found: ${companionPath}`);
-  }
-  const companionSize = fileSize(companionPath);
-  if (companionSize < 10) {
-    BLOCKING_ERROR(`Companion file empty or too small: ${companionPath} (${companionSize} bytes)`);
-  }
-}
-
-// Check 6: File paths must be valid C# identifiers (no spaces, apostrophes, accents)
-// Reference: references/entity-canonicalization.md
-for (const [cat, files] of Object.entries(ftc)) {
-  for (const file of (files || [])) {
-    const filePath = file.path || file;
-    // Extract filename without extension
-    const fileName = filePath.split('/').pop().replace(/\.(cs|tsx|ts|json)$/, '');
-    // Check for illegal characters in C# file names
-    if (/[\s'àâäéèêëïîôùûüçÀÂÄÉÈÊËÏÎÔÙÛÜÇ]/.test(fileName)) {
-      BLOCKING_ERROR(`${cat}: File path contains illegal characters for C# identifier: "${filePath}" — entity name must be canonicalized (see references/entity-canonicalization.md)`);
-    }
-  }
-}
-```
-
-Display verification table showing all 8 categories match between module JSON files and prd.json.
+Verify PRD structure against module handoff, display verification table showing all 8 categories match between module JSON files and prd.json.
 
 ### 3. Generate modules-queue.json (if 2+ modules)
 
@@ -170,37 +103,9 @@ Write to: `.ralph/progress.txt`
 
 ### 5. Update Project Index (status tracking)
 
-> **ba-006:** No global `docs/index.json` manifest. Projects are autonomous.
-> Update the project's own `{docs_dir}/index.json` with handoff status instead.
+> **Reference:** See loaded context `project-index-update.md` for ba-006 primary flow and legacy pre-ba-006 fallback structure.
 
-**Update logic:**
-
-1. Read `{docs_dir}/index.json` (project master index)
-2. Update status to `"handed-off"` for each processed module
-3. Update `metadata.lastModified` timestamp
-4. Write back
-5. Display: "Project index updated: {docs_dir}/index.json (status: handed-off)"
-
-**Legacy (pre-ba-006):** If `docs/index.json` global manifest exists, also update it for backward compatibility:
-```json
-{
-  "version": "1.0",
-  "updatedAt": "{ISO timestamp}",
-  "analyses": [
-    {
-      "appCode": "{app_code}",
-      "appName": "{application_name}",
-      "moduleCode": null | "{module_code}",
-      "moduleName": "{module_name}",
-      "version": "{version}",
-      "status": "handed-off",
-      "featureDescription": "{description}",
-      "path": "{projectSlug}/v{version}/index.json",
-      "updatedAt": "{ISO timestamp}"
-    }
-  ]
-}
-```
+Update the project's own `{docs_dir}/index.json` with handoff status. If legacy `docs/index.json` exists, update it for backward compatibility.
 
 ### 6. Display Completion Summary
 
@@ -256,3 +161,9 @@ Artifacts generated:
 9. Each companion file is non-empty (>10 bytes)
 
 **IF any check fails -> fix before completing.**
+
+## POST-CHECK GLOBAL (BLOCKING — ba-009 fix)
+
+> **Reference:** See loaded context `handoff-global-validation.md` for module-level integrity, global file checks, surplus file detection, and result handling.
+
+Verifies overall handoff integrity across all modules — blocks completion if expected files are missing.