--- name: ba-audit-sections description: > Audits the menu sections of a `.smartstack/ba/` project — module-section coverage, duplicate/ambiguous sections, sibling state-variant sections (same primary subject), cross-module and cross-app duplication (SEC-001..008 — SEC-006 retired, 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, Bash] # Bash: the audit-ba engine (deterministic mechanical rules) --- # 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. ## Deterministic engine — how this audit runs The MECHANICAL rules of this dimension are evaluated by the shared `audit-ba` CLI (see `/ba-audit-run`) — **never by reading the corpus yourself, never by spawning per-module subagents** (the 394M-token incident shape). Your only job here is the judgment residue. 1. **Run the engine, scoped to this dimension**: ```bash npx --prefer-offline tsx skills/business-analyse/audit-run/cli/audit-ba/index.ts \ --spec '{"baRoot":".smartstack/ba","scope":{"app":"","module":""},"dimensions":["sections"]}' ``` 2. **Exit 3 = parsing suspect -> STOP.** A control counter disagrees with the parser (`report.parseControl.perDoc`): fix the doc's form or report the parser bug, then re-run. Never « complete by hand » — no green verdict may be born from a silent parser. 3. **Arbitrate** every `report.judgmentNeeded[]` entry of this dimension (SEC-003, SEC-004, SEC-008 (arbitration side), XAPP-002, XAPP-003) from its `question` + `excerpts` ONLY (they are complete by contract — needing more is a CLI bug to report, never a license to read the corpus). Write the decisions JSON to the scratchpad and re-run with `\"judgments\":\"\"` — the CLI merges, consumes the pending items and rewrites the verdict itself (you never write verdict markdown). 4. **Chat summary** (3-6 lines, business terms): the PARSE TOTALS (say the counts — that is how a « 0 erreur » stays verifiable), err/warn counts, remaining judgments, and the fix skill each finding names. The CLI writes the verdict to `.smartstack/ba///_audit/sections.md` (existing format — anchor, `Verdict :` header, emoji sections; `0 err` = pass for the downstream gate). The rule texts below remain the AUTHORITATIVE spec — the CLI registry is drift-tested against them. ## Scope - **Module scope** (default): audit one module — apply SEC-001, SEC-002, SEC-005, SEC-008 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///_audit/sections.md`. - **App scope**: apply SEC-001, SEC-002, SEC-005, SEC-008 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 — RETIRED (empty sections are legitimate) - **Do NOT apply — never re-add.** This rule used to warn on sections with zero resources. Decision (2026-06, aligned with the Studio): a section with 0 resources is a NORMAL, fully legitimate state — resources are an optional 4th level, most sections never need one, and warning on them trained users to invent artificial resources. The number stays burned (no renumbering); a section with no resources produces NO finding under any rule. ### 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 `///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`. ### SEC-008 — No section that is a state/variant/subset of a sibling (same primary subject) - **Severity**: err (if a sibling pair shares its primary subject), ok (if none) - **Why**: a section groups the sub-set of the module that deals with **ONE subject** — two sibling sections about the same subject is an illogical split: the "variant" one is a state filter dressed up as a workspace. Module Facturation: `factures` + `avoirs` are two distinct subjects → ok; `factures` + `factures-editees` share the subject Facture ("éditée" is a lifecycle state) → err. The creation-side rule lives in `create-menu/levels/sections.md` ("A section is a DISTINCT ENTITY, never a STATE FILTER of a sibling") — this rule is its on-disk enforcement. - Check: for EVERY pair of sections under the audited module, determine from the labels, codes and `## Contexte` whether one section is merely a lifecycle-state / period / status subset of the other's primary entity/subject (typical signals: `-editees`, `-archivees`, `-cloturees`, `-en-attente`, "historique", "archive", a year/period suffix on an otherwise identical subject). - **Contextual analysis REQUIRED** (same discipline as SEC-003): the pair is a violation ONLY when the candidate brings nothing but the filter. If its `## Contexte` documents its OWN columns, actions or permissions that the sibling does not cover, it may stand — state that justification explicitly in the finding. Decide from the menu tree only (labels / codes / `## Contexte`); downstream phases are blocked while the menu is audited and MUST NOT be referenced. - **err**: name the pair (with module context), the shared subject, and the demotion path: fold the variant into its sibling as a router filter / status tab, or requalify it as a resource under the sibling if it has its own columns/actions. - **fix**: `/ba-create-menu` (demote/merge); if downstream docs already reference the demoted section (UC/SCR/BR/RBAC codes — see SEC-007), run `/ba-reconcile-menu` after the rename/deletion. ## 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. **Never suggest a domain a built-in platform app already provides** (see `/ba-create-menu` § "Built-in platform apps": `administration`, `support`, `hr`, `api`, `myspace`, plus Auth/Notifications/Workflows/Data-export) — that would reintroduce the very duplicate the menu skill exists to prevent. Suggest only genuine CLIENT gaps: - Enterprise suite → Finance/Accounting (NOT "Administration" — built-in) - SaaS platform → Billing (NOT "Admin Console" — the `administration` app is built-in) - **Never suggest « GED / Documents / DMS » as a missing app**: the platform ships the storage primitive (`IFileStorageService` — Normal/Legal tiers, Local + Azure Blob). Business documents are modeled as METADATA entities INSIDE the module that owns them (attachments pattern — `development/backend/data-layer/references/file-storage.md`, rule C-6 of `/ba-create-data-model`), never as a standalone document-management application. - **HR-heavy**: Payroll / Talent Management / Recruitment are NOT new apps — the platform already ships the `hr` app; suggest them as **new modules to add UNDER `hr`** (extension), never as standalone applications. - Report: the missing capability, and whether it is a new client app or an extension of a built-in app. - **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 — ` + `_ · Verdict : 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.