---
name: ba-audit-sections
description: >
  Audits the menu sections of a `.smartstack/ba/` project — module-section
  coverage, duplicate/ambiguous/empty sections, cross-module and cross-app
  duplication (SEC-001..007, XAPP-001..003). Reads the section nodes under a
  module, writes a verdict to `_audit/sections.md`. Run after `/ba-create-menu`
  or as part of pre-dev readiness.
allowed-tools: [Read, Write, Glob, Grep]
---

# ba-audit-sections — Menu sections audit

You audit the sections of a `.smartstack/ba/` project against the rules below and
write a verdict file. The rules are unchanged from the SmartStack convention; only
the I/O is file-based.

## File model — how to audit

1. **Read state**: `Glob .smartstack/ba/**/index.md` to rebuild the tree. Sections
   are the folders directly under a module
   (`.smartstack/ba/<APP>/<MODULE>/<section>/index.md`). Read each section's
   `index.md` (label, `## Contexte`, `## Enfants` — the children listed there are
   the section's resources). The module folder's own `index.md` `## Enfants` lists
   the sections.
2. **Apply** the rules SEC-001..006 (and XAPP-001..003 at the wider scopes, below)
   at the requested scope.
3. **Write** the verdict to the audited module's `_audit/sections.md`:
   `.smartstack/ba/<APP>/<MODULE>/_audit/sections.md` (use the audit-verdict
   skeleton from `_workflow/doc-templates.md`). Then print a 3–6 line business
   summary in chat.

There is no database, no envelope, no i18n label codes — the `.md` verdict IS the
record. The verdict header (`0 err` = pass) is what a downstream gate reads.

## Scope

- **Module scope** (default): audit one module — apply SEC-001, SEC-002, SEC-005,
  SEC-006 to its sections (the module-internal rules). Skip SEC-003, SEC-004 and
  the XAPP rules — cross-module / cross-app duplication isn't a single-module
  concern. The verdict lives at `.smartstack/ba/<APP>/<MODULE>/_audit/sections.md`.
- **App scope**: apply SEC-001, SEC-002, SEC-005, SEC-006 to every module under the
  app, **plus** SEC-003 (cross-module duplicate names) and the XAPP rules
  (cross-app). Write one `_audit/sections.md` per module audited.
- **Project scope**: as app scope, and also apply SEC-004 (duplicate names across
  other applications / analyses in the tree). Decide every cross-cutting rule from
  the menu tree only — section labels/codes and business semantics; never reach
  into downstream phases (actors, use cases, data model), which are blocked while
  the menu is being audited.

## Rules

### SEC-001 — Module must have at least 1 section
- **Severity**: err (if 0 sections), ok (if >= 1)
- **ok**: the module exposes at least one section (state how many).
- **err**: the module has zero sections — it can't expose any UI, which blocks
  downstream phases.
- **fix**: `/ba-create-menu`

### SEC-002 — No duplicate section codes within the module
- **Severity**: err (if duplicates found), ok (if none)
- Check: count occurrences of each section code (folder name + `index.md` anchor
  code) within one module.
- **err**: two or more sections share the same code (list the offending codes).
- **fix**: `/ba-create-menu`

### SEC-003 — No section names duplicated across other modules (same analysis)
- **Severity**: warn (if true functional duplicate found), ok (if no duplicates or contextually different)
- Check: compare section labels (case-insensitive) across ALL modules in the analysis
- **Contextual analysis REQUIRED**: When two sections share the same name across
  different modules, you MUST determine whether they represent:
  - **True duplicate** (same business function, same data, same purpose — should be
    consolidated or renamed) → flag as `warn`
  - **Contextually different** (same generic name but different business domain,
    different data, different actors — each is legitimate in its own module) → `ok`
- Use ONLY the menu tree hierarchy (application code/label + module code/label
  + section codes/labels) and business semantics to decide. Downstream phases
  (actors, use cases, data model) are BLOCKED while menu is being audited and
  MUST NOT be referenced here. Examples:
  - "Pipeline" in CRM (sales opportunities) vs "Pipeline" in HR/Recrutement
    (candidatures) → contextually different → ok
  - "Dashboard" in Module A vs "Dashboard" in Module B → each module's dashboard
    is contextual → ok
  - "Reports" in Sales and "Reports" in Marketing within the same app, both doing
    the same KPI exports → true duplicate → warn
- Do NOT use a hardcoded whitelist. Analyze the business semantics.
- **warn**: name the duplicated sections with their module context.
- **fix**: `/ba-create-menu`

### SEC-004 — No section names duplicated across other active analyses
- **Severity**: warn (if found), ok (if none)
- Check: if the tree includes more than one analysis / application, compare section
  labels across them and report functional duplicates.
- **warn**: list the duplicated section names across applications.
- **fix**: `/ba-create-menu`

### SEC-005 — No ambiguous section names
- **Severity**: warn (if found), ok (if none)
- **Ambiguous names** (case-insensitive): `settings`, `options`, `configuration`, `config`,
  `parametres`, `utilities`, `tools`, `outils`, `misc`, `other`, `divers`, `autre`
- **warn**: list the sections whose label is one of the ambiguous names.
- **fix**: `/ba-create-menu`

### SEC-006 — No empty sections (0 resources)
- **Severity**: warn (if found)
- Check: sections with zero resources — no children listed under `## Enfants` and
  no resource sub-folders.
- **warn**: list the empty sections.
- **fix**: `/ba-create-menu`

### SEC-007 — Sections referenced in downstream docs still exist in the menu
- **Severity**: err (if any orphan reference is found), ok (otherwise)
- **Why**: when a section is removed from the menu (`/ba-create-menu`) after
  downstream content was generated, the UC/SCR/BR/RBAC codes that carry the
  deleted section in their (APP,MOD,SEC) triplet become orphans. The downstream
  files (`use-case.md`, `screen.md`, `règles-métier.md`, `rbac.md`) silently
  keep those blocks — `/ba-develop` then crashes on invalid section codes
  during scaffolding.
- **Check**: for each code matching
  `(UC|SCR|BR|RBAC)-{APP}-{MOD}-{SEC}-NNN` extracted via Grep from every
  `**/use-case.md`, `**/screen.md`, `**/règles-métier.md`, `**/rbac.md` under
  the audited scope, the triplet `(APP, MOD, SEC)` MUST correspond to an
  existing `<APP>/<MOD>/<sec-folder>/index.md` in the tree (section code
  derived from the kebab folder name via uppercase + `-` → `_`).
- **err**: list each orphan code with its file path verbatim.
- **fix**: `/ba-reconcile-menu` (preflight that renames or deletes orphans
  with user validation), then re-run `/ba-loop`.

## Cross-Application Patterns (reported in the sections verdict)

**Gate**: Only apply XAPP rules when audit scope = project or application.
When scope = module, skip all XAPP rules — emit zero XAPP findings.

### XAPP-001 — Duplicate section/module pattern across applications
- **Severity**: warn
- Check: section or module names like "Rapports", "Reports", "Parametrage", "Settings",
  "Portail", "Portal" that appear in 2+ different applications.
- Report: the repeated pattern and the applications it appears in.
- **fix**: `/ba-create-menu`

### XAPP-002 — Missing standard application for the business domain
- **Severity**: warn
- Based on the applications defined, identify commonly expected but absent apps:
  - Enterprise suite → Finance/Accounting, Administration/Backoffice, GED/Documents
  - SaaS platform → Billing, Admin Console
  - HR-heavy → Payroll, Talent Management
- Report: the missing application and why it is commonly expected.
- **fix**: `/ba-create-menu`

### XAPP-003 — Functional overlap between modules in different apps
- **Severity**: warn
- Check: modules in different apps that cover the same business function
  (e.g., "Competences" in HR and "Training" in Academy both manage skills).
- Report: the two overlapping modules (app.module) and a description of the overlap.
- **fix**: `/ba-create-menu`

## Output

Write `_audit/sections.md` per the doc-templates skeleton:
- Header `# Audit sections — <MODULE>` + `_<date> · Verdict : <emoji> N warn · M err · K ok_`.
- `## ✅ Conforme`, `## ⚠️ Avertissements`, `## ❌ Bloquants` sections; one bullet
  per finding. For `warn`/`err`: what's wrong (offending codes **bold**), why it
  matters, and a `→` fix naming `/ba-create-menu` (sections are authored there).
- Keep the rule codes (`SEC-001`, `XAPP-001`, …) **bold** so they stay greppable,
  but explain them in business terms.
- Re-Write the whole file each run (overwrite — it's a fresh verdict).

Then a 3–6 line chat summary in the user's language — business terms, no rule
codes. If any `err`, state clearly that the sections must be fixed before moving on.

## Used by the readiness orchestrator

`/ba-audit-pre-dev` runs every dimension and aggregates the verdicts. When invoked
by it, still write `_audit/sections.md` as usual — the orchestrator reads these files.
