@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/create-menu/levels/modules.md

@@ -0,0 +1,81 @@
+---
+phase: menu
+kind: level
+level: modules
+---
+
+# Level 2 — Modules
+
+> Scope strict: propose **modules** for ONE application. No sections/resources/
+> entities/rules/screens. The phase boundary, write protocol and code/label
+> rules live in `SKILL.md`. Work one app at a time.
+
+## Research before proposing
+
+Web research is encouraged to identify a complete module set (not to invent
+entities/rules). Do 1-2 searches silently ("[domain] software features",
+"[domain] application modules"), then **list every candidate in prose** grouped
+by importance (Fundamental / Recommended / Advanced) before asking the user to
+validate. Cite sources in one line. Never announce research then stop — propose
+in the same turn.
+
+## Two-axis pattern (managers + concerned parties)
+
+Every application has two audiences:
+- **Managers** — administer the data (HR staff, admins).
+- **Concerned parties** — those impacted, scoped to their own data.
+
+For each app ask "who manages? who is concerned?" and propose a **portal module**
+for the concerned party when relevant:
+
+| Domain | Portal module | Content |
+|--------|---------------|---------|
+| HR | Employee portal | my profile, my leave, my payslips |
+| CRM | Client portal | my invoices, my tickets, my contracts |
+| Project | Collaborator portal | my tasks, my timesheets |
+
+## Module rules
+
+- Each application has **≥ 2 modules**; each module justifies **≥ 1** functional
+  section (else merge it).
+- Configuration = a dedicated module (Settings = app config; reference data =
+  code lists). Never a `SETTINGS` section.
+- Check against SmartStack Core (see `SKILL.md` prohibitions) — don't duplicate
+  built-ins.
+- Propose broadly (the user prunes); 1-2 word, single-concept labels; no
+  `& / \ | < > "` (split, or make the two facets sections inside one module).
+- Optional `## Hors-périmètre` in the module `index.md` for module-specific
+  exclusions (don't repeat the parent app's — it cascades implicitly).
+
+## Fusion — merging two modules
+
+When the user asks to merge module A into module B:
+
+1. Read both modules' `index.md` and their child folders.
+2. Detect conflicts: a child section code present under BOTH. For each conflict
+   ask the user (AskUserQuestion): keep target / keep source / rename source /
+   merge contents.
+3. Re-parent the source's child folders under the target (move folders, fix each
+   `## Enfants` list and the `level=`/`code=` anchors if a code changes).
+4. Merge the two `## Contexte` sections semantically into the target's `index.md`.
+5. Delete the source module folder and remove it from the parent app's
+   `## Enfants`. Confirm the deletion before removing.
+
+For a plain rename, just edit the module `index.md` + the parent link. For a
+delete without re-parenting, remove the folder after confirmation.
+
+## Edge cases
+
+| Situation | Action |
+|-----------|--------|
+| User unchecks a fundamental | Ask why, accept with justification |
+| Module outside the proposal | Add it — research isn't exhaustive |
+| App has only 1 module | Suggest merging with another app |
+| Module has no identifiable section | Merge with a neighbour |
+
+## After validation
+
+Write each module under its app: `.smartstack/ba/<APP>/<MODULE>/index.md`
+(level=module) + the six placeholders, and add it to the app's `## Enfants`.
+Acknowledge in one line and ask (AskUserQuestion) whether to define this module's
+sections, do another module, or pause.

package/templates/skills/business-analyse/create-menu/levels/resources.md

@@ -0,0 +1,75 @@
+---
+phase: menu
+kind: level
+level: resources
+---
+
+# Level 4 — Resources
+
+> Scope strict: propose **resources** only — optional sub-menu entries under a
+> section. Default is **none**. No entities/rules/screens/KPI/chart specs. The
+> phase boundary, write protocol and code/label rules live in `SKILL.md`.
+
+## Opt-in by default
+
+A resource is an OPTIONAL sub-menu of a section, created **only** when a section
+is too voluminous and a sub-division helps navigation. **Most sections need no
+resource** — the default is none. Never create a resource for a UI widget, a KPI,
+a chart, or a CRUD form (those are internal to the section / handled by the router).
+
+### Not a resource
+
+| Section type | Why | Correct |
+|--------------|-----|---------|
+| Dashboard (KPIs + charts) | the section IS the dashboard | no resource |
+| Business listing (Employés, Commandes…) | router provides the filterable list | no resource |
+| Simple form / entry | router handles CRUD | no resource |
+| Calendar / kanban / org chart | specialized section, not a resource | no resource |
+
+## When to propose a resource — 2 trigger patterns only
+
+Permission-based splits are NOT evaluated here (that's the RBAC phase).
+
+**Pattern 1 — Reports / Analyses section.** Trigger: the section label starts with
+Rapport(s) / Report(s) / Analyse(s) / Analytics / Reporting. Each resource = ONE
+coherent report telling ONE business story (a metadata anchor: code + label +
+context; the KPI/chart layout comes later in screens). One report = one resource;
+never one-per-KPI.
+
+**Pattern 2 — Multi-entity sub-grouping.** Trigger: the section is a polymorphic
+container (Tiers, Tenants, Contacts, Bénéficiaires…) or the user mentions several
+distinct types in it. Each resource = one entity acting as a pre-filter with its
+**own columns or actions** — not a mere status dropdown. If the partition doesn't
+change columns/actions, don't propose it.
+
+## How to propose
+
+Default: emit no resource, move on. When a trigger matches: first confirm intent
+(AskUserQuestion, yes/no), then if yes ask a multi-select for the concrete
+resources. If the user keeps none, accept and move on. Resource labels are short
+single-concept names (1-3 words), no `& / \ | < > "`; `context` is optional;
+`resourceType` defaults to `Custom` at this stage.
+
+## After validation
+
+Write each resource under its section:
+`.smartstack/ba/<APP>/<MODULE>/<section>/<resource>/index.md` (level=resource) +
+the six placeholders, and add it to the section's `## Enfants`.
+
+## End of menu architecture — hand off to actors
+
+When the tree is complete for the project, recap it as a compact tree and ask the
+user (AskUserQuestion) to **Valider** or **Corriger** — exactly two choices. Open
+design questions go in prose ("à confirmer plus tard"), never in the choices.
+
+On **Valider**: acknowledge in one line ("Structure validée — on établit l'ordre
+d'analyse des modules"), make sure every node `index.md` is written, and hand off
+to `/ba-create-ba-order` (phase 1.5 — BA ordering). The canonical order is fixed:
+menu → **ba-order** → actors → use cases → rules → RBAC → data model → screens.
+Never offer PRD/MCD/other as the next step here. On **Corriger**: parse the free
+text, adjust, re-Write the affected `index.md`, re-recap, re-ask the same two
+choices.
+
+> Menu quality (duplicate/orphan/empty checks, MENU-001..005) is verified by the
+> separate `/ba-audit-menu` skill, which reads the tree and writes its verdict —
+> you don't emit audit findings from here.

package/templates/skills/business-analyse/create-menu/levels/sections.md

@@ -0,0 +1,82 @@
+---
+phase: menu
+kind: level
+level: sections
+---
+
+# Level 3 — Sections
+
+> Scope strict: propose **sections** for one or more modules. No resources/
+> entities/rules/screens. Section code + label + context only. The phase
+> boundary, write protocol and code/label rules live in `SKILL.md`.
+
+## What a section is
+
+A section is an **autonomous workspace** in the menu — a distinct activity the
+user performs in a module, with its own entry point, its own functionality, and
+potentially its own permissions. Each section answers: "what distinct activity
+does the user do here?"
+
+## A section is a NOUN, never a VERB (one exception)
+
+A section is **where** the user works; an action is **what** they do. Actions are
+buttons or nested routes, never sibling sections. Test: translate the code and
+read it — if it's a verb, it's not a section.
+
+| Pattern | Verdict |
+|---------|---------|
+| Noun — `factures`, `enveloppes`, `mouvements`, `directory` | ✅ Section |
+| Exception — `list` / `liste` | ✅ Section (maps to a list view) |
+| `create`, `edit`, `detail`, `close`, `emettre`, `valider`, `archiver`, … | ❌ Action — button/route |
+| `parametres`, `settings` | ❌ This is a MODULE, not a section |
+
+## A section is a DISTINCT ENTITY, never a STATE FILTER of a sibling
+
+Two sections in the same module must describe **different entities or workflows**,
+not the same entity at different lifecycle stages. A "history"/"archive"/"closed"
+view of an existing list belongs INSIDE that list (a router filter or status tab),
+or as a Step-4 resource if it has its own columns/actions — never as a sibling.
+
+Test: does candidate Y share its primary entity with a sibling X, filtering only
+a subset (status/period/state)? If yes → Y is a filter, not a section. **Default
+when unsure = filter.** A section is justified only by its own columns, actions,
+or permissions — not by a `WHERE status='closed'`.
+
+## Code → screen type (downstream impact)
+
+The kebab-case `code` you choose drives the SmartComponent that `/ba-create-screen`
+generates later. Pick the suffix on purpose:
+
+| Section code ends with | Screen type later |
+|------------------------|-------------------|
+| `-home`, `-overview`, `-dashboard` | `SmartSectionHome` / `SmartDashboard` |
+| `list`, `liste`, `-list`, `-grid`, `-search` | `SmartListView` |
+| `-board`, `-workflow`, `-pipeline` | `SmartKanban` |
+
+`-detail`/`-edit`/`-create`/`-form` are NOT valid section codes (they're actions).
+A section code must not equal its parent module's code; default to `list` for a
+list or `dashboard` for an aggregate view.
+
+## Naming
+
+- Short single-concept phrases (1-4 words); no `& / \ | < > "`.
+- "X et Y": same activity → one umbrella label; two distinct activities → two
+  sections with distinct codes.
+- Always pick BOTH a kebab-case `code` and a clear user-language `label` — never
+  echo the raw code as the label.
+
+## Edge cases
+
+| Situation | Action |
+|-----------|--------|
+| User proposes a verb as a section | Explain noun=section, action=button; re-propose with the entity noun |
+| Module has only 1 section | Acceptable if simple |
+| No section justifies the module | Propose merging the module |
+| User wants a "Settings" section | Explain it's a module |
+
+## After validation
+
+Write each section under its module: `.smartstack/ba/<APP>/<MODULE>/<section>/index.md`
+(level=section) + the six placeholders, and add it to the module's `## Enfants`.
+Acknowledge in one line and ask (AskUserQuestion) whether to add resources to a
+voluminous section, move to another module, or finish the menu.

package/templates/skills/business-analyse/create-plan-development/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ba-create-plan-development
+description: >
+  Generates a phased development plan ordering modules by their cross-module
+  data-model dependencies. Reads entité.md across selected applications, builds
+  a dependency graph, topological-sorts into parallel development waves, and
+  writes dev-plan.md. Invoke between the BA audit phase and /ba-develop.
+group: G
+argument-hint: '<APP1> [APP2] …'
+allowed-tools: [Bash, Read, Glob]  # Bash: CLI invocation; file writes handled by the CLI
+---
+
+# ba-create-plan-development — Phased Development Planning
+
+## Your role
+
+You are a **development planner**. You read the data models (`entité.md`) of
+one or more applications, extract cross-module FK dependencies, and produce a
+phased development plan that tells the team **which modules to develop first**.
+
+You do not write code. You invoke the deterministic CLI and present its output.
+
+## When to use
+
+- **After Phase 6** (data model) — at minimum, every module must have its
+  `entité.md`. Ideally run after `/ba-audit-pre-dev` so readiness info is available.
+- **Before `/ba-develop`** — the plan tells you the safe order to run `/ba-develop`
+  across modules.
+
+## Prerequisites
+
+- `.smartstack/ba/` tree with at least one application and one module.
+- `entité.md` should exist for each module (modules without it get a warning).
+- Optional: `_audit/prd.md` per module (for readiness status in the plan).
+
+## How it works
+
+1. **Parse** — reads every `entité.md` under the selected applications.
+2. **Extract** — identifies cross-module FK references in the attribute table
+   (pattern: `FK cross-module vers APP/MODULE.Entity`). Core refs (`auth_*`,
+   `nav_*`, `tnt_*`) are excluded — they're always available.
+3. **Graph** — builds a directed dependency graph between modules.
+4. **Sort** — topological sort (Kahn's algorithm) into parallel waves.
+   Cycles are detected (Tarjan SCC) and grouped in the same wave with a warning.
+5. **Wave 0** — modules referenced as dependencies but NOT in the selected
+   applications appear as external prerequisites with a ⚠️ warning.
+6. **Write** — outputs `.smartstack/ba/_plan/dev-plan.md` with summary, wave
+   tables, Mermaid dependency graph, and next steps.
+
+## Invocation
+
+Ask the user which applications to include, then invoke the CLI:
+
+```bash
+npx tsx skills/business-analyse/create-plan-development/cli/create-plan-development/index.ts \
+  --spec '{"baRoot": ".smartstack/ba", "apps": ["CRM", "BILLING"], "includeReadiness": true}'
+```
+
+### Input
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `baRoot` | string | yes | Path to `.smartstack/ba/` |
+| `apps` | string[] | yes | UPPERCASE application codes |
+| `includeReadiness` | boolean | no (default: true) | Read `_audit/prd.md` for GO/NO-GO status |
+
+### Output
+
+`GenerateEnvelope` on stdout. The plan file is written to
+`.smartstack/ba/_plan/dev-plan.md`.
+
+## Output format
+
+The plan includes:
+
+1. **Summary table** — app count, module count, wave count, cycle count
+2. **Wave 0 — External Prerequisites** — modules not in the selected apps but
+   referenced as FK targets
+3. **Wave 1+ — Development waves** — modules grouped by dependency level, with
+   entity count, dependencies, and PRD readiness status
+4. **Mermaid graph** — visual dependency diagram with subgraphs per wave
+5. **Warnings** — missing `entité.md`, cycles, undocumented FKs
+6. **Next steps** — actionable guidance for running `/ba-develop`
+
+## Cross-module FK convention
+
+This skill relies on the `entité.md` attribute table convention defined in
+`create-data-model/levels/relationships.md`:
+
+- **Same-module FK** → declared as a `Relation` (not parsed by this skill)
+- **Cross-module FK** → plain `Guid` attribute with description:
+  `FK cross-module vers APP/MODULE.Entity`
+- **SmartStack Core** → plain `Guid` attribute: `FK Core auth_Users` (excluded)

package/templates/skills/business-analyse/create-plan-development/cli/create-plan-development/__tests__/graph.test.ts

@@ -0,0 +1,271 @@
+/**
+ * graph.test.ts — Tests for dependency graph, cycle detection, and topological sort.
+ */
+import { describe, it, expect } from 'vitest';
+import { buildPlan, tarjanSCC } from '../graph.js';
+import type { ModuleInfo, ModuleKey, Wave } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Create a minimal ModuleInfo for testing. */
+function mod(
+  app: string,
+  module: string,
+  deps: Array<{ targetApp: string; targetModule: string }> = [],
+  entityCount = 1,
+): ModuleInfo {
+  return {
+    appCode: app,
+    moduleCode: module,
+    key: `${app}/${module}` as ModuleKey,
+    entities: Array.from({ length: entityCount }, (_, i) => ({
+      code: `ENT-${String(i + 1).padStart(3, '0')}`,
+      name: `Entity${i + 1}`,
+    })),
+    crossModuleDeps: deps.map((d) => ({
+      sourceEntity: 'SomeEntity',
+      sourceAttribute: `${d.targetModule}Id`,
+      targetApp: d.targetApp,
+      targetModule: d.targetModule,
+      targetEntity: 'SomeTarget',
+    })),
+    coreRefs: [],
+    hasEntiteMd: true,
+  };
+}
+
+/** Get internal (non-external) waves. */
+function devWaves(waves: Wave[]): Wave[] {
+  return waves.filter((w) => w.level > 0);
+}
+
+/** Get module keys from a wave. */
+function waveKeys(wave: Wave): string[] {
+  return wave.modules.map((m) => m.key).sort();
+}
+
+// ---------------------------------------------------------------------------
+// Tarjan SCC
+// ---------------------------------------------------------------------------
+
+describe('tarjanSCC', () => {
+  it('finds no cycles in a DAG', () => {
+    const nodes: ModuleKey[] = ['A/X' as ModuleKey, 'A/Y' as ModuleKey];
+    const adj = new Map<ModuleKey, Set<ModuleKey>>([
+      ['A/X' as ModuleKey, new Set(['A/Y' as ModuleKey])],
+      ['A/Y' as ModuleKey, new Set()],
+    ]);
+    const cycles = tarjanSCC(nodes, adj);
+    expect(cycles).toHaveLength(0);
+  });
+
+  it('finds a 2-node cycle', () => {
+    const nodes: ModuleKey[] = ['A/X' as ModuleKey, 'A/Y' as ModuleKey];
+    const adj = new Map<ModuleKey, Set<ModuleKey>>([
+      ['A/X' as ModuleKey, new Set(['A/Y' as ModuleKey])],
+      ['A/Y' as ModuleKey, new Set(['A/X' as ModuleKey])],
+    ]);
+    const cycles = tarjanSCC(nodes, adj);
+    expect(cycles).toHaveLength(1);
+    expect(cycles[0].sort()).toEqual(['A/X', 'A/Y']);
+  });
+
+  it('finds a 3-node cycle', () => {
+    const nodes: ModuleKey[] = [
+      'A/X' as ModuleKey,
+      'A/Y' as ModuleKey,
+      'A/Z' as ModuleKey,
+    ];
+    const adj = new Map<ModuleKey, Set<ModuleKey>>([
+      ['A/X' as ModuleKey, new Set(['A/Y' as ModuleKey])],
+      ['A/Y' as ModuleKey, new Set(['A/Z' as ModuleKey])],
+      ['A/Z' as ModuleKey, new Set(['A/X' as ModuleKey])],
+    ]);
+    const cycles = tarjanSCC(nodes, adj);
+    expect(cycles).toHaveLength(1);
+    expect(cycles[0].sort()).toEqual(['A/X', 'A/Y', 'A/Z']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildPlan — topological sort into waves
+// ---------------------------------------------------------------------------
+
+describe('buildPlan', () => {
+  it('places all independent modules in Wave 1', () => {
+    const modules = [
+      mod('CRM', 'CONTACTS'),
+      mod('CRM', 'SETTINGS'),
+      mod('BILLING', 'PRODUCTS'),
+    ];
+    const plan = buildPlan(modules, ['CRM', 'BILLING']);
+    const waves = devWaves(plan.waves);
+
+    expect(waves).toHaveLength(1);
+    expect(waves[0].level).toBe(1);
+    expect(waveKeys(waves[0])).toEqual([
+      'BILLING/PRODUCTS',
+      'CRM/CONTACTS',
+      'CRM/SETTINGS',
+    ]);
+    expect(plan.cycles).toHaveLength(0);
+  });
+
+  it('chains dependent modules across waves', () => {
+    // PIPELINE depends on CONTACTS
+    const modules = [
+      mod('CRM', 'CONTACTS'),
+      mod('CRM', 'PIPELINE', [{ targetApp: 'CRM', targetModule: 'CONTACTS' }]),
+    ];
+    const plan = buildPlan(modules, ['CRM']);
+    const waves = devWaves(plan.waves);
+
+    expect(waves).toHaveLength(2);
+    expect(waveKeys(waves[0])).toEqual(['CRM/CONTACTS']);
+    expect(waveKeys(waves[1])).toEqual(['CRM/PIPELINE']);
+  });
+
+  it('handles diamond dependencies', () => {
+    // D depends on B and C; B and C are independent
+    const modules = [
+      mod('A', 'B'),
+      mod('A', 'C'),
+      mod('A', 'D', [
+        { targetApp: 'A', targetModule: 'B' },
+        { targetApp: 'A', targetModule: 'C' },
+      ]),
+    ];
+    const plan = buildPlan(modules, ['A']);
+    const waves = devWaves(plan.waves);
+
+    expect(waves).toHaveLength(2);
+    expect(waveKeys(waves[0])).toEqual(['A/B', 'A/C']);
+    expect(waveKeys(waves[1])).toEqual(['A/D']);
+  });
+
+  it('handles a linear chain A → B → C', () => {
+    const modules = [
+      mod('A', 'C'),
+      mod('A', 'B', [{ targetApp: 'A', targetModule: 'C' }]),
+      mod('A', 'A', [{ targetApp: 'A', targetModule: 'B' }]),
+    ];
+    const plan = buildPlan(modules, ['A']);
+    const waves = devWaves(plan.waves);
+
+    expect(waves).toHaveLength(3);
+    expect(waveKeys(waves[0])).toEqual(['A/C']);
+    expect(waveKeys(waves[1])).toEqual(['A/B']);
+    expect(waveKeys(waves[2])).toEqual(['A/A']);
+  });
+
+  it('places external deps in Wave 0', () => {
+    // INVOICES depends on CRM/CONTACTS, but CRM is not in scope
+    const modules = [
+      mod('BILLING', 'INVOICES', [
+        { targetApp: 'CRM', targetModule: 'CONTACTS' },
+      ]),
+    ];
+    const plan = buildPlan(modules, ['BILLING']);
+
+    const wave0 = plan.waves.find((w) => w.level === 0);
+    expect(wave0).toBeDefined();
+    expect(wave0!.modules).toHaveLength(1);
+    expect(wave0!.modules[0].key).toBe('CRM/CONTACTS');
+    expect(wave0!.modules[0].isExternal).toBe(true);
+    expect(wave0!.modules[0].referencedBy).toContain('BILLING/INVOICES');
+
+    // INVOICES should be in Wave 1 (its only dep is external)
+    const waves = devWaves(plan.waves);
+    expect(waves).toHaveLength(1);
+    expect(waveKeys(waves[0])).toEqual(['BILLING/INVOICES']);
+  });
+
+  it('detects and groups cycles in the same wave', () => {
+    // A depends on B, B depends on A
+    const modules = [
+      mod('X', 'A', [{ targetApp: 'X', targetModule: 'B' }]),
+      mod('X', 'B', [{ targetApp: 'X', targetModule: 'A' }]),
+    ];
+    const plan = buildPlan(modules, ['X']);
+
+    expect(plan.cycles).toHaveLength(1);
+    expect(plan.cycles[0].sort()).toEqual(['X/A', 'X/B']);
+
+    // Both should be in the same wave
+    const waves = devWaves(plan.waves);
+    expect(waves).toHaveLength(1);
+    expect(waveKeys(waves[0])).toEqual(['X/A', 'X/B']);
+  });
+
+  it('handles cycle plus non-cycle modules', () => {
+    // C depends on cycle (A↔B), D is independent
+    const modules = [
+      mod('X', 'A', [{ targetApp: 'X', targetModule: 'B' }]),
+      mod('X', 'B', [{ targetApp: 'X', targetModule: 'A' }]),
+      mod('X', 'C', [{ targetApp: 'X', targetModule: 'A' }]),
+      mod('X', 'D'),
+    ];
+    const plan = buildPlan(modules, ['X']);
+
+    expect(plan.cycles).toHaveLength(1);
+
+    const waves = devWaves(plan.waves);
+    // D and A↔B have no external deps → could be Wave 1
+    // C depends on A → Wave 2
+    // A↔B are collapsed into one group at Wave 1
+
+    // Find which wave has D and cycle group
+    const wave1Keys = waveKeys(waves[0]);
+    expect(wave1Keys).toContain('X/D');
+    expect(wave1Keys).toContain('X/A');
+    expect(wave1Keys).toContain('X/B');
+
+    // C should be in Wave 2
+    const wave2 = waves.find((w) => waveKeys(w).includes('X/C'));
+    expect(wave2).toBeDefined();
+    expect(wave2!.level).toBeGreaterThan(waves[0].level);
+  });
+
+  it('handles cross-app dependencies within scope', () => {
+    // BILLING/INVOICES depends on CRM/CONTACTS, both in scope
+    const modules = [
+      mod('CRM', 'CONTACTS'),
+      mod('BILLING', 'INVOICES', [
+        { targetApp: 'CRM', targetModule: 'CONTACTS' },
+      ]),
+    ];
+    const plan = buildPlan(modules, ['CRM', 'BILLING']);
+
+    // No external deps
+    expect(plan.waves.find((w) => w.level === 0)).toBeUndefined();
+
+    const waves = devWaves(plan.waves);
+    expect(waves).toHaveLength(2);
+    expect(waveKeys(waves[0])).toEqual(['CRM/CONTACTS']);
+    expect(waveKeys(waves[1])).toEqual(['BILLING/INVOICES']);
+  });
+
+  it('reports correct totalCrossModuleDeps', () => {
+    const modules = [
+      mod('CRM', 'CONTACTS'),
+      mod('CRM', 'PIPELINE', [
+        { targetApp: 'CRM', targetModule: 'CONTACTS' },
+      ]),
+      mod('BILLING', 'INVOICES', [
+        { targetApp: 'CRM', targetModule: 'CONTACTS' },
+        { targetApp: 'CRM', targetModule: 'PIPELINE' },
+      ]),
+    ];
+    const plan = buildPlan(modules, ['CRM', 'BILLING']);
+    expect(plan.totalCrossModuleDeps).toBe(3);
+  });
+
+  it('handles empty module list', () => {
+    const plan = buildPlan([], ['CRM']);
+    expect(plan.waves).toHaveLength(0);
+    expect(plan.cycles).toHaveLength(0);
+    expect(plan.totalModules).toBe(0);
+  });
+});