@atlashub/smartstack-cli 4.74.0 → 4.76.0

package/templates/skills/business-analyse-develop/steps/step-05-report.md

@@ -65,137 +65,8 @@ if (fileExists(queuePath)) {
 
 ### 1d. Handoff Reconciliation (Post-Execution Validation)
 
-> **LESSON LEARNED (audit ba-002):** Simple "missing files" warnings were ignored.
-> Structured reconciliation tables make gaps impossible to miss.
+See `report-reconciliation.md` for reconciliation logic (file coverage, business rule coverage, API endpoint coverage, and build/test verification).
 
-```javascript
-// === RECONCILIATION 1: Handoff File Coverage ===
-const filesToCreate = prd.implementation?.filesToCreate || {};
-const handoffReconciliation = { categories: [], totalDeclared: 0, totalPresent: 0, missingFiles: [] };
-
-for (const [cat, files] of Object.entries(filesToCreate)) {
-  let declared = 0, present = 0;
-  for (const file of (files || [])) {
-    declared++;
-    const filePath = file.path || file;
-    if (fileExists(filePath)) {
-      present++;
-    } else {
-      handoffReconciliation.missingFiles.push({ category: cat, path: filePath });
-    }
-  }
-  handoffReconciliation.categories.push({
-    category: cat, declared, present, missing: declared - present,
-    coverage: declared > 0 ? Math.round((present / declared) * 100) : 100
-  });
-  handoffReconciliation.totalDeclared += declared;
-  handoffReconciliation.totalPresent += present;
-}
-
-const totalHandoffCoverage = handoffReconciliation.totalDeclared > 0
-  ? Math.round((handoffReconciliation.totalPresent / handoffReconciliation.totalDeclared) * 100)
-  : 100;
-
-// === RECONCILIATION 2: Business Rule Coverage ===
-const brMapping = prd.implementation?.brToCodeMapping || [];
-const brReconciliation = { total: brMapping.length, implemented: 0, missing: [], notTested: [] };
-
-for (const br of brMapping) {
-  const componentFile = br.component || br.file;
-  const methodName = br.method || br.function;
-
-  if (!componentFile || !fileExists(componentFile)) {
-    brReconciliation.missing.push({ id: br.id, rule: br.rule, reason: 'file not found' });
-    continue;
-  }
-  if (methodName) {
-    const content = readFile(componentFile);
-    if (!content.includes(methodName)) {
-      brReconciliation.missing.push({ id: br.id, rule: br.rule, reason: `method ${methodName} not found` });
-      continue;
-    }
-  }
-  brReconciliation.implemented++;
-
-  if (br.testFile && !fileExists(br.testFile)) {
-    brReconciliation.notTested.push({ id: br.id, rule: br.rule });
-  }
-}
-
-// === RECONCILIATION 3: API Endpoint Coverage ===
-const apiEndpoints = prd.implementation?.apiEndpointSummary || [];
-const apiReconciliation = { total: apiEndpoints.length, found: 0, missing: [] };
-
-const ctrlFilesForReconciliation = glob('src/**/Controllers/**/*Controller.cs');
-for (const ep of apiEndpoints) {
-  const opName = ep.operation || ep.name;
-  let found = false;
-  for (const f of ctrlFilesForReconciliation) {
-    const content = readFile(f);
-    if (content.includes(opName)) { found = true; break; }
-  }
-  if (found) {
-    apiReconciliation.found++;
-  } else {
-    apiReconciliation.missing.push({ operation: opName, method: ep.method, path: ep.path });
-  }
-}
-
-// Log summary
-console.log(`Handoff files: ${handoffReconciliation.totalPresent}/${handoffReconciliation.totalDeclared} (${totalHandoffCoverage}%)`);
-console.log(`Business rules: ${brReconciliation.implemented}/${brReconciliation.total} implemented`);
-console.log(`API endpoints: ${apiReconciliation.found}/${apiReconciliation.total} found`);
-```
-
-### 1e. Final Build & Test Verification (TRUTH CHECK)
-
-> **LESSON LEARNED (audit ba-002):** "92/92 COMPLETE" + "Build PASS" was reported but the code
-> had compilation errors and critical security flaws. The report MUST reflect actual build/test
-> state, not just PRD task statuses.
-
-```bash
-# REAL build verification — overrides any previous "Build PASS" claim
-dotnet build --no-restore --verbosity quiet
-FINAL_BUILD_RC=$?
-
-FINAL_TEST_RC=-1
-if [ $FINAL_BUILD_RC -eq 0 ]; then
-  dotnet test --no-build --verbosity quiet
-  FINAL_TEST_RC=$?
-fi
-```
-
-```javascript
-// Override PRD-based build/test status with REAL results
-const buildStatus = FINAL_BUILD_RC === 0 ? 'PASS' : 'FAIL';
-const testStatus = FINAL_TEST_RC === 0 ? 'PASS' : (FINAL_TEST_RC === -1 ? 'SKIPPED (build failed)' : 'FAIL');
-
-// CRITICAL: If build fails despite all tasks "completed", flag this prominently
-if (FINAL_BUILD_RC !== 0 && stats.tasks.completed === stats.tasks.total) {
-  console.error('INTEGRITY WARNING: All tasks marked COMPLETE but build FAILS');
-  console.error('This indicates phantom task completion — review code quality');
-  stats.buildIntegrityWarning = true;
-}
-```
-
-### 1f. MCP Security Scan (Final Gate)
-
-```javascript
-// Quick MCP security validation on the final codebase
-const securityScan = await mcp__smartstack__validate_security();
-const conventionScan = await mcp__smartstack__validate_conventions();
-
-// Check for write endpoints with Read permissions (semantic permission check)
-const permissionWarnings = [];
-const ctrlFiles = glob('src/**/Controllers/**/*Controller.cs');
-for (const f of ctrlFiles) {
-  const content = readFile(f);
-  const writeWithRead = content.matchAll(/\[(HttpPost|HttpPut|HttpDelete|HttpPatch)[^\]]*\][^[]*\[RequirePermission\([^\)]*\.Read\)\]/gs);
-  for (const m of writeWithRead) {
-    permissionWarnings.push(`${f}: ${m[1]} uses Read permission`);
-  }
-}
-```
 
 ### 1c. Test Metrics (from PRD)
 
@@ -209,146 +80,9 @@ const testsFailed = testTasks.filter(t => t.status === 'failed').length;
 
 ## 2. Generate Report
 
-Write to `.ralph/reports/{feature-slug}.md`:
-
-```markdown
-# Feature Report: {feature}
-
-## Summary
-| Field | Value |
-|-------|-------|
-| Status | {status} |
-| Iterations | {iterations_used} / {max} |
-| Branch | {branch} |
-| Duration | {totalDuration}s ({min} min) |
-| Execution | Delegated to /apex |
-
-## Tasks
-| # | Task | Category | Status | Commit |
-|---|------|----------|--------|--------|
-{for each task:}
-| {id} | {description} | {category} | {status_emoji} | {commit_hash} |
-
-**{completed}/{total} completed, {failed} failed, {blocked} blocked**
-
-{if moduleStats:}
-## Modules
-| Module | Status | Tasks | Completed | Failed | Files | Commits |
-|--------|--------|-------|-----------|--------|-------|---------|
-{for each mod:}
-| {code} | {status} | {total} | {completed} | {failed} | {filesCreated} | {commits} |
-
-**{completedModules}/{totalModules} modules completed**
-{end if}
-
-{if prd._sectionSplit?.enabled:}
-## Section Split Execution
-| Phase | Type | Section | Entities | Status |
-|-------|------|---------|----------|--------|
-{for each phase:}
-| {phase} | {type} | {sectionCode || '-'} | {entities.length} | {status} |
-
-{end if}
-
-{if handoffReconciliation.totalDeclared > 0:}
-## Handoff Reconciliation
-
-### File Coverage by Category
-| Category | Declared | Present | Missing | Coverage |
-|----------|----------|---------|---------|----------|
-{for each cat in handoffReconciliation.categories:}
-| {category} | {declared} | {present} | {missing} | {coverage}% |
-{end for}
-
-**Total: {totalPresent}/{totalDeclared} ({totalHandoffCoverage}%)**
+Write to `.ralph/reports/{feature-slug}.md` using the template structure from `report-template.md`.
 
-{if handoffReconciliation.missingFiles.length > 0:}
-### Missing Files
-{for each mf in handoffReconciliation.missingFiles:}
-- **{mf.category}**: `{mf.path}`
-{end for}
-{end if}
-{end if}
-
-{if brReconciliation.total > 0:}
-### Business Rule Coverage
-| Metric | Value |
-|--------|-------|
-| Total Rules | {brReconciliation.total} |
-| Implemented | {brReconciliation.implemented} |
-| Missing | {brReconciliation.missing.length} |
-| Not Tested | {brReconciliation.notTested.length} |
-
-{if brReconciliation.missing.length > 0:}
-**Missing BR implementations:**
-{for each br in brReconciliation.missing:}
-- `{br.id}`: {br.rule} — {br.reason}
-{end for}
-{end if}
-{end if}
-
-{if apiReconciliation.total > 0:}
-### API Endpoint Coverage
-| Metric | Value |
-|--------|-------|
-| Total Endpoints | {apiReconciliation.total} |
-| Found | {apiReconciliation.found} |
-| Missing | {apiReconciliation.missing.length} |
-
-{if apiReconciliation.missing.length > 0:}
-**Missing API endpoints:**
-{for each ep in apiReconciliation.missing:}
-- `{ep.method} {ep.path}` — operation: `{ep.operation}`
-{end for}
-{end if}
-{end if}
-
-## Build & Test Verification (Actual)
-
-> These results come from REAL `dotnet build` and `dotnet test` execution,
-> not from PRD task statuses.
-
-| Check | Result |
-|-------|--------|
-| `dotnet build` | {buildStatus} |
-| `dotnet test` | {testStatus} |
-| MCP validate_security | {securityScan.status} |
-| MCP validate_conventions | {conventionScan.status} |
-| Permission semantic check | {permissionWarnings.length === 0 ? 'PASS' : `${permissionWarnings.length} issues`} |
-
-{if stats.buildIntegrityWarning:}
-> **INTEGRITY WARNING:** All tasks marked COMPLETE but the build FAILS.
-> This means some generated code references types or methods that don't exist.
-> Review the build output and fix before considering this feature done.
-{end if}
-
-{if permissionWarnings.length > 0:}
-> **PERMISSION WARNINGS:** Write endpoints using Read permissions detected:
-{for each warning:}
-> - {warning}
-{end for}
-{end if}
-
-## Test Metrics (PRD-based)
-| Metric | Value |
-|--------|-------|
-| Test Tasks | {testTasks.length} |
-| Passed | {testsPassed} |
-| Failed | {testsFailed} |
-
-## Failed Tasks
-{table of failed tasks with error messages, or "None"}
-
-## Files
-- Created: {filesCreated.length}
-- Modified: {filesModified.length}
-
-## Commits
-{unique commits list}
-
----
-*Auto-generated by Ralph Loop — SmartStack CLI*
-```
+Populate all variables from loaded data (stats, moduleStats, handoffReconciliation, brReconciliation, apiReconciliation, buildStatus, testStatus, permissionWarnings, testTasks, filesCreated, filesModified).
 
 ## 3. Finalize
 

package/templates/skills/business-analyse-handoff/SKILL.md

@@ -89,3 +89,13 @@ Transforms consolidated BA data into structured handoff and PRD files.
 ## Entry Point
 
 **FIRST ACTION:** Load `steps/step-00-validate.md`
+
+<success_criteria>
+- Feature BA validee et statut "consolidated" confirme
+- Handoff data genere avec 8 categories (domain, application, infrastructure, api, frontend, seedData, tests, documentation)
+- handoff.json enrichi par module avec BR-to-code et API summary
+- PRD files generes : .ralph/prd-{moduleCode}.json par module
+- progress.txt cree avec task breakdown
+- modules-queue.json cree avec ordre topologique
+- Manifeste BA mis a jour avec statut "handed-off"
+</success_criteria>

package/templates/skills/business-analyse-handoff/references/agent-handoff-transform-prompt.md

@@ -0,0 +1,211 @@
+# Agent Transform Prompt for ba-writer (Module Handoff Generation)
+
+## MANDATORY CONSTRAINTS
+
+**INTERDICTION:** You must create EXACTLY 7 files and NOTHING ELSE. No README, SUMMARY, MANIFEST, INDEX, CHECKLIST.
+
+## YOUR TASK
+
+Transform module "{moduleCode}" for handoff.
+
+## Output EXACT (7 files)
+
+1. WRITE `{moduleDir}/handoff.json` (8 categories, brMapping, apiEndpoints, specificationFiles)
+2. COPY VERBATIM `.ralph/prd-{moduleCode}.entities.json`
+3. COPY VERBATIM `.ralph/prd-{moduleCode}.rules.json`
+4. COPY VERBATIM `.ralph/prd-{moduleCode}.usecases.json`
+5. COPY VERBATIM `.ralph/prd-{moduleCode}.screens.json`
+6. COPY VERBATIM `.ralph/prd-{moduleCode}.permissions.json`
+7. GENERATE `.ralph/prd-{moduleCode}.json` (PRD v3.0.0)
+
+Return: `{ "moduleCode": "{moduleCode}", "filesCreated": 7, "errors": [], "complexity": "..." }`
+
+## INPUT
+
+- Module BA directory: `{moduleDir}` (ba-006: `docs/{projectSlug}/v{X.Y}/{appKebab}/{moduleKebab}/`)
+- Application code: `{appCode}`
+- Application name: `{appName}`
+- Feature description: `{featureDescription}`
+- Module index: `{moduleDir}/index.json`
+
+## INSTRUCTIONS
+
+### 1. Read Input Files
+
+Read these 5 files from `{moduleDir}` (ba-006 location: `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"`)
+
+### 2. 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 || []`
+- `rules[].examples`: prefer `rule.examples[]` (`{input, expected}`); fallback: wrap `rule.example` string as `[{input: rule.example, expected: ""}]`
+- `rules[].statement`: prefer `rule.statement`; fallback: `rule.description`
+- `rules[].id`: prefer `rule.id`; fallback: `rule.code`
+- `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.
+
+### 3. Determine Complexity
+
+| Criteria | Simple | Medium | Complex |
+|----------|--------|--------|---------|
+| Entities | ≤3 | ≤6 | >6 |
+| Use Cases | ≤5 | ≤12 | >12 |
+| Business Rules | ≤10 | ≤20 | >20 |
+
+Classify the module based on these thresholds.
+
+### 4. Generate API Endpoints
+
+From use cases and entities, auto-generate REST endpoints:
+
+- 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` as-is.
+
+### 5. Enrich Section UC/BR
+
+Using `sectionCode` from `usecases.json` and `rules.json`, link each UC and BR to its section.
+
+### 6. Entity Name Canonicalization (MANDATORY)
+
+Before generating any file paths, canonicalize ALL entity names from `entities.json`:
+
+1. Load `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.
+
+### 7. Build Handoff Data (8 Categories)
+
+Load `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 specifics:** Each page as separate entry, FK fields, ALL pages use `/ui-components`.
+
+**Routes specifics:** PascalCase module codes → kebab-case (NEVER include `/business/` prefix).
+
+### 8. Map Business Rules to Code
+
+Load `references/handoff-mappings.md` for mapping rules.
+
+For each rule: `ruleId`, `title`, `module`, `severity`, `implementationPoints[]`.
+
+### 9. Handle personRoleConfig
+
+If any entity has `personRoleConfig`, copy it verbatim into handoff.
+
+### 10. Generate Seed Data
+
+Load `references/handoff-seeddata-generation.md` for core seed generation.
+
+- `category: "core"` → Navigation, Permissions, Roles
+- `category: "business"` → Domain-specific data
+
+### 11. Map Entity to Domain
+
+Load `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`
+
+### 12. Declare Dependencies per File Entry
+
+| Layer | Dependencies |
+|-------|-------------|
+| domain | `[]` |
+| infrastructure | `["domain"]` |
+| application | `["domain"]` |
+| api | `["application"]` |
+| seedData | `["domain", "infrastructure"]` |
+| frontend | `["api"]` |
+| tests | `["domain", "application", "infrastructure", "api"]` |
+| documentation | `[]` |
+
+### 13. 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}`
+
+### 14. Write 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"
+}
+```
+
+### 15. 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"`
+
+## RETURN VALUE
+
+Return a single JSON line:
+
+```json
+{ "moduleCode": "{moduleCode}", "filesCreated": 7, "errors": [], "complexity": "simple|medium|complex" }
+```

package/templates/skills/business-analyse-handoff/references/context-isolation-pattern.md

@@ -0,0 +1,47 @@
+# Context Isolation Architecture
+
+## Pattern Overview
+
+```
+Main conversation (orchestrator):
+  ├─ Determine topological order
+  ├─ FOR each module:
+  │   └─ Agent(ba-writer) ──► reads 5 files, writes 7 files, returns 1-line JSON
+  │                           (isolated context: ~500-1000 lines per module)
+  └─ Collect 1-line results only, display summary
+```
+
+## Why Context Isolation is CRITICAL
+
+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.
+
+## Orchestration Pattern (ba-009 fix)
+
+The orchestrator does NOT read detailed agent results.
+
+Each Agent returns a single compact JSON confirmation:
+
+```json
+{
+  "moduleCode": "Employees",
+  "filesCreated": 7,
+  "errors": [],
+  "complexity": "simple"
+}
+```
+
+The orchestrator stores ONLY this summary (1 line per module).
+
+**Orchestrator context budget:** ~200 lines max (12 modules × ~15 lines each).
+
+## Execution Flow
+
+1. **Determine topological order** from step-00 data
+2. **For EACH module in topological order:**
+   - Call Agent(ba-writer) with isolated context
+   - Receive 1-line JSON confirmation
+   - Store only the confirmation
+3. **Collect all confirmations** and display summary
+4. **Never load detailed agent results** back into main conversation
+
+This pattern prevents context accumulation across modules and enables processing of large multi-module projects.

package/templates/skills/business-analyse-handoff/references/handoff-file-inventory.md

@@ -0,0 +1,49 @@
+# Handoff File Inventory
+
+## FICHIERS A CREER — LISTE FERMEE (ba-009 fix)
+
+Exhaustive inventory. ONLY these files must be created. ABSOLUTE PROHIBITION on creating README, SUMMARY, MANIFEST, INDEX, CHECKLIST, ARTIFACTS, EXECUTION-SUMMARY, etc.
+
+## Per-Module Files (Created 7 times, once per module {M})
+
+| # | Filename | Location |
+|---|----------|----------|
+| 1 | `handoff.json` | `{moduleDir}/handoff.json` (in docs/) |
+| 2 | `prd-{M}.json` | `.ralph/prd-{M}.json` (PRD master v3.0.0) |
+| 3 | `prd-{M}.entities.json` | `.ralph/` (VERBATIM copy) |
+| 4 | `prd-{M}.rules.json` | `.ralph/` (VERBATIM copy) |
+| 5 | `prd-{M}.usecases.json` | `.ralph/` (VERBATIM copy) |
+| 6 | `prd-{M}.screens.json` | `.ralph/` (VERBATIM copy) |
+| 7 | `prd-{M}.permissions.json` | `.ralph/` (VERBATIM copy) |
+
+**Subtotal per module:** 7 files
+
+## Global Files (Created once)
+
+| # | Filename | Location |
+|---|----------|----------|
+| 8 | `modules-queue.json` | `.ralph/modules-queue.json` |
+| 9 | `progress.txt` | `.ralph/progress.txt` |
+
+**Subtotal:** 2 files
+
+## Total
+
+**TOTAL: (7 × N modules) + 2 global files**
+
+For a 3-module project: 7×3 + 2 = 23 files exactly.
+
+## Companion File Naming — REGEX CANONIQUE
+
+Each companion MUST match: `prd-{ModuleCode}.{suffix}.json`
+
+where `suffix ∈ { entities | rules | usecases | screens | permissions }`
+
+### FORBIDDEN VARIANTS (ABSOLUTE PROHIBITION)
+
+- ✗ `prd-Module.useCases.json` (wrong casing — must be `usecases`)
+- ✗ `prd-Module.businessRules.json` (wrong name — must be `rules`)
+- ✗ `prd-Module.api-spec.json` (not planned)
+- ✗ `prd-Module.summary.json` (not planned)
+
+All companion filenames must use **lowercase** suffixes and EXACTLY the 5 defined names.