---
name: ba-audit-screens
description: >
  Audits the screen specs of a `.smartstack/ba/` section — coverage, entity refs,
  SmartComponent coherence, navigation integrity, related-tabs, home-page
  hierarchy, UC traceability, custom-actions structure (SCR-001..013). Reads the
  section `screen.md` plus the module `entité.md`/`rbac.md` and the section
  `use-case.md`, writes a verdict to `_audit/screen.md`. Run after
  `/ba-create-screen` or as part of pre-dev readiness.
allowed-tools: [Read, Write, Glob, Grep]
---

# ba-audit-screens — Screen specifications audit

You audit the screen specs 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. The thirteen rules cover the full SmartComponent type
set: `SmartListView`, `SmartForm`, `SmartDashboard`, `SmartKanban`, `SmartCard`,
`SmartAppHome`, `SmartModuleHome`, `SmartSectionHome`. The legacy `SmartFilter`
type is forbidden (covered by SCR-010), and the **custom-actions metadata**
introduced by ba-create-screen (SCR-011/012/013) is verified end-to-end so the
downstream pipeline never silently drops a non-CRUD button.

## File model — how to audit

1. **Read state**: `Glob .smartstack/ba/**/index.md` to rebuild the tree. For each
   section in scope, Read its `screen.md`
   (`.smartstack/ba/<APP>/<MODULE>/<section>[/<resource>]/screen.md`). To validate
   refs, also Read the parent module's `entité.md` (entity codes/names) and
   `rbac.md` (permissions), and the section's `use-case.md` (UC codes). The
   `index.md` files give you the application → module → section counts (for the
   home-page rules) and the navigation targets resolve against `SCR-…` codes
   Grepped across the tree's `screen.md` files.
2. **Apply** the rules SCR-001..013 (below) at the requested scope.
3. **Write** the verdict to `_audit/screen.md` under the audited section:
   `.smartstack/ba/<APP>/<MODULE>/<section>/_audit/screen.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

- **Section scope** (default): audit one section — apply SCR-001..010 to its
  screens, resolving refs against the parent module's `entité.md`/`rbac.md` and
  the section's `use-case.md`. Navigation targets (SCR-008) resolve against every
  `SCR-…` code in the analysis.
- **Module scope**: apply the rules to every section under the module; the
  module-level rules (SCR-001, SCR-007) and the app-level rule (SCR-006) span the
  whole subtree.
- The verdict file lives at the audited section's `_audit/screen.md`.

## Rules

### SCR-001 — At least 1 screen exists per module
- **Severity**: err (if 0), ok (if >= 1)
- Count the `SCR-…` screens across the module's sections.
- Fix: `/ba-create-screen`.

### SCR-002 — Every section has at least 1 screen
- **Severity**: warn (if uncovered sections), ok (if all covered)
- Fix: `/ba-create-screen`.

### SCR-003 — Screen entity references point to existing entities
- **Severity**: err (if broken refs), ok (if all valid)
- Check: screen's entityRef matches an entity code OR entity name in the data model
- Skip when `entityRef` is null AND screen type is `SmartDashboard`/`SmartAppHome`/`SmartModuleHome`/`SmartSectionHome` (these aggregate via widgets)
- Fix: `/ba-create-screen`.

### SCR-004 — Entity-bound screens have an entity reference
- **Severity**: warn (if missing), ok (if all have)
- Check: screenType ∈ {`SmartListView`, `SmartForm`, `SmartCard`} → entityRef must be non-empty
- `SmartKanban` SHOULD have entityRef (workflow entity with status)
- `SmartDashboard`/`SmartAppHome`/`SmartModuleHome`/`SmartSectionHome` do NOT need entityRef on the screen (they aggregate through widgets)
- Fix: `/ba-create-screen`.

### SCR-005 — All screens are linked to at least 1 use case
- **Severity**: warn (if unlinked), ok (if all linked)
- Fix: `/ba-create-screen`.

### SCR-006 — Application landing page (SmartAppHome) exists when ≥2 modules
- **Severity**: warn (if missing), ok (if all multi-module apps have one)
- Check: for each application with ≥2 modules, at least one screen of type `SmartAppHome` exists with that `applicationCode`
- Fix: `/ba-create-screen`.

### SCR-007 — Module landing page (SmartModuleHome) exists when ≥2 sections
- **Severity**: warn (if missing), ok (if all multi-section modules have one)
- Check: for each module with ≥2 sections, at least one screen of type `SmartModuleHome` exists with that `applicationCode`/`moduleCode`
- Fix: `/ba-create-screen`.

### SCR-008 — Navigation targets reference existing screens
- **Severity**: err (if any broken target), ok (if all valid)
- Check every navigation field for an existing screen `code` in this analysis:
  - `SmartListView.config.rowClickTarget`
  - `SmartCard.config.clickTarget`
  - `SmartKanban.config.rowClickTarget`
  - `SmartForm.config.relatedTabs[].screenTarget`
  - `SmartAppHome.config.quickLinks[].screenTarget`
  - `SmartModuleHome.config.quickLinks[].screenTarget`
  - `SmartSectionHome.config.quickLinks[].screenTarget`
- Fix: `/ba-create-screen`.

### SCR-009 — Detail forms expose related collections via relatedTabs
- **Severity**: warn (if missing on candidate forms), ok otherwise
- Check: for each `SmartForm` in `mode: "edit"` or `mode: "detail"` whose entity has ≥1 incoming 1:N FK in the data model, `config.relatedTabs[]` should be non-empty
- Skip portal/read-only modules where related navigation is intentionally suppressed
- Fix: `/ba-create-screen`.

### SCR-010 — No legacy SmartFilter screens remain
- **Severity**: err (if any present), ok (if none)
- Check: no screen has `screenType === "SmartFilter"`. The type is removed; filters live inside `SmartListView.config.filters`.
- Fix: `/ba-create-screen`.
- **migration hint**: for each affected section, fold the SmartFilter into the matching SmartTable/SmartListView (move `config.fields[]` into `SmartListView.config.filters.fields[]`) and re-emit a single `SmartListView` screen.

### SCR-011 — Custom actions carry the mandatory metadata
- **Severity**: err (if any custom action is missing a required field), ok
- Check: for every `- **Actions personnalisées** :` sub-bullet of every screen,
  all of `code`, `kind`, `scope`, `permission`, `label` are present and
  well-formed. The `code` regex is camelCase `^[a-z][a-zA-Z0-9]*$`; the
  `permission` regex accepts 3 segments (section) or 4 segments (resource):
  `^[a-z][a-z0-9-]*\.[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)?\.[a-z][a-z0-9-]*$`.
- Then branch on `kind`:
  - `kind: api` requires `endpoint` (kebab `^[a-z][a-z0-9-]*$`) +
    `httpMethod` ∈ {GET,POST,PUT,PATCH,DELETE} + `UC: UC-…`. When `endpoint`
    is absent the default is `kebab(code)` — the audit accepts the absence
    but still verifies kebab-ness once the default is applied.
  - `kind: navigate` requires `targetScreen: SCR-…` OR a `targetRoute`
    string, and MUST NOT carry `endpoint` / `httpMethod` / `payloadDto`.
- This is the gate that catches free-text custom actions silently dropped by
  `ba-create-prd`.
- Fix: `/ba-create-screen`.

### SCR-012 — Custom action endpoints are unique per entity
- **Severity**: err (if any duplicate endpoint within one entity's screens), ok
- Check: across every screen `bound` to the same entity (`entityRef` match) of
  the audited module, no two custom actions of `kind: api` share the
  `(httpMethod, scope, endpoint)` triplet. A duplicate would emit a duplicate
  `[HttpVerb("<endpoint>")]` on the controller (compile error) or two service
  methods of the same name (TypeScript collision).
- Fix: `/ba-create-screen`.

### SCR-013 — Navigate targets resolve to an existing screen
- **Severity**: err (any broken `targetScreen`), ok otherwise
- Check: every custom action with `kind: navigate` AND `targetScreen: SCR-…`
  references a screen code present in this audit's analysis (any module of
  the same application). Reuses the resolution table built for SCR-008.
- Custom actions using `targetRoute` (free-text route helper) are skipped by
  this rule — they are validated later by the per-page contract audit
  (`/ba-audit-prd`, PRD-100) once the route resolution is wired by
  `ba-create-prd`.
- Fix: `/ba-create-screen`.

## Output

Write `_audit/screen.md` per the doc-templates skeleton:
- Header `# Audit screen — <APP> / <MODULE> / <section>` + `_<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-screen`.
- 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, not rule
codes. If any `err`, state clearly that the screens 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/screen.md` as usual — the orchestrator reads these files.
