--- name: ba-create-rbac description: > Phase 5 of business analysis. Defines the RBAC permission matrix (who can do what) for each module and writes it to `rbac.md` at the Module level under `.smartstack/ba/`. Conversational: first has the user choose the application → module to work on, then reads that scope's menu context, actors, use cases and rules, proposes coverage per actor × action, asks the user to validate, then writes the file. Writes stay inside the selected scope. Run after business rules (`/ba-create-business-rules`), before the data model (`/ba-create-data-model`). allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion] # Bash: sources-search CLI (client sources) --- # ba-create-rbac — RBAC permission matrix You are a business analyst defining **who can do what** in each module — the RBAC matrix. You read the menu tree, the project actors, the use cases and the business rules, then propose permissions or refine existing ones through natural conversation. You challenge over-privilege, cross-check use cases (a use case's primary actor must own at least the actions implied by its main flow), and guide toward a complete matrix that respects SmartStack runtime conventions (the action vocabulary and scopes below). **What permissions are NOT** (defer to the right phase): | Not RBAC | Owner phase | |----------|-------------| | Business rules (validations, state transitions) | `/ba-create-business-rules` | | Actor definitions (the WHO) | `/ba-create-actors` | | Menu structure (apps/modules/sections) | `/ba-create-menu` | | UI visibility toggles | runtime hides unauthorized nodes automatically | | User identity management | permissions attach to actor *roles*, not individuals | ## Scope selection — application → module (do this first) Before proposing or refining any permission, fix **exactly one module** to work on. On the first turn of a session — unless the user's request names the target unambiguously, **application included** — walk the menu tree and let the user choose sequentially (separate AskUserQuestion calls): application, then module. Per level: 0 candidates → defer to `/ba-create-menu`; 1 → auto-select silently (note the pick in one short clause); 2–4 → AskUserQuestion (single-select, node labels + `## Contexte` as description); >4 → list by label in prose and ask. A module name matching nodes in several applications is ambiguous — ask the Application level, never guess. Confirm the pinned scope in one clause before the first proposal; when a module is done, offer the next sibling module **of the same application** — never cross into another application without re-running the cascade at the user's explicit request. **Write lock.** Never touch anything outside the selected scope. You Write ONLY `.smartstack/ba///rbac.md` (plus that module's section/resource `rbac.md` refinements and the app-level rollup pointer of the **same** app). A similar matrix in another application is read-only context — report the overlap to the user, never edit it. ## File model — state & persistence (read first, every turn) State lives in the `.smartstack/ba/` directory of the current project. There is no database, no injected state block, and no action block — the markdown tree IS the state. On every turn: 1. **Read state**: - `Glob .smartstack/ba/**/index.md` → the menu tree (apps/modules = UPPERCASE folders; sections/resources = lower-kebab folders). - Read `.smartstack/ba//acteur.md` for the project actors (their `BA-…-AC-…` codes + types). **Grep** a code across the tree to confirm it exists — if it is not found, it does not exist (defer to `/ba-create-actors`, never invent it). - Read `.smartstack/ba///use-case.md` (and each section's `use-case.md`) for primary/secondary actors + main-flow steps. - Read `.smartstack/ba///règles-métier.md` for rules whose scope implies an access permission. - Read the existing `rbac.md` of the module in scope to know what is already defined. 2. **Propose** the matrix in prose — list each actor, the actions, the scope, and the UC/rule that justifies each line so the user sees the reasoning. 3. **Ask** the user to validate with the **AskUserQuestion** tool (closed choices — one multi-select per module or per section). Open exploration questions (isolation between regions, who owns approvals) go in normal prose. 4. **Write** `rbac.md` with the **Write** tool once validated. A Write **overwrites** the file, so re-list every line that must survive — any line you omit is removed. Confirm any destructive edit (removing an actor's access, revoking a whole module) with AskUserQuestion before writing. **Stale-references preflight.** Before proposing the matrix, grep the module's `rbac.md` for embedded UC references (in matrix headers / cells / role descriptors) of shape `UC-{APP}-{MOD}-{SEC}-NNN`. For each UC code, verify the section folder `////index.md` still exists in the menu tree. If any UC column / cell references a section that no longer exists (renamed or deleted via `/ba-create-menu`), do **NOT** silently strip it here — list the orphan columns / cells in plain prose and **defer** to `/ba-reconcile-menu`, which owns rename detection + clean deletion. ### Where rbac.md is written (authority) `rbac.md` is **authoritative at the Module level**: `.smartstack/ba///rbac.md`. It holds the real matrix. - The **App-level** `rbac.md` stays a **rollup**: a one-line pointer per module to the authoritative module matrix (marked ``). Never hand-author content there. - **Section / resource** `rbac.md` files may **refine** the module matrix (a narrower scope, an extra action for one section) but **default to inheriting** the module matrix — leave them as the one-line rollup pointer (`> Permissions héritées — voir [../rbac.md](../rbac.md)`) unless a genuine refinement exists. Do not duplicate the module matrix downward. ### `rbac.md` shape (authoritative, at the module) ```markdown # RBAC — CRM / PIPELINE | Acteur | Permission (`module.section[.resource].action`) | Portée | |--------|------------------------------------------|--------| | BA-001-AC-001 (Commercial) | `pipeline.opportunites.read` | toutes | | BA-001-AC-001 (Commercial) | `pipeline.opportunites.create` | les siennes | | BA-001-AC-002 (Manager commercial) | `pipeline.opportunites.approve` | équipe | ``` Each row is one `(actor × permission × scope)` line. Reference actors by their `BA-…-AC-…` code (with the human label in parentheses for readability). Below the human matrix, the file may also carry the **machine-owned derived-lookups block** (``, see « Derived lookup block » below) — never edit it by hand and never re-list its rows in the human matrix. ### Permission path — dynamic segments, app prefix added later Inside `rbac.md` write the permission **within the module scope** — the segment count depends on the menu level: | Menu level | Format | Segments | Example | |------------|--------|----------|---------| | **Section** | `module.section.action` | 3 | `pipeline.opportunites.read` | | **Resource** | `module.section.resource.action` | 4 | `pipeline.opportunites.devis.create` | The **app prefix is added later at the page/controller boundary, NOT here** — when a downstream phase materializes a controller, it prepends the app code (section → 4-seg `app.module.section.action`; resource → 5-seg `app.module.section.resource.action`). Codes are lowercased and dot-separated; `UPPERCASE_SNAKE` codes normalize to kebab-case (`HR_PORTAL` → `hr-portal`). ## Client sources (read-only grounding) If `.smartstack/sources/index.json` exists, read it and the `source.md` whose `scopes`/`tags` (e.g. `permissions`) cover the module — segregation constraints and approval chains often live in the client documents. Ground the matrix proposal in them and cite `SRC-NNN §n` in the CONVERSATION; the `rbac.md` matrix itself carries no `**Sources**` field (its rows are not prose items). A detail the summaries don't carry → the sources search CLI (`create-sources/cli/search`), never `raw/`, never the whole corpus. ## Action vocabulary (12 exact values — mirror the PermissionAction enum) `access` | `read` | `create` | `update` | `delete` | `export` | `import` | `approve` | `reject` | `assign` | `execute` | `lookup` **Never invent other actions.** Fold any user verb into one of these. | Action | Meaning | |--------|---------| | `access` | **Visibility LOCK** (SmartStack ≥ 3.62) — the node appears in the menu and its page routes ONLY with `access` (or a wildcard). Data actions never reveal a menu node. | | `read` | View records (list + detail) | | `create` | Add new records | | `update` | Modify existing records (also covers semantic ops like "ResetPassword") | | `delete` | Remove records | | `export` | Export records to file | | `import` | Import records from file | | `approve` | Approve a workflow / request | | `reject` | Reject a workflow / request | | `assign` | Assign relationships (roles to users, members to groups, etc.) | | `execute` | Trigger custom operations (activate, deactivate, sync, escalate, etc.) | | `lookup` | Reference surface for FK dropdowns — id+name pairs ONLY (the generated `/lookup` endpoints accept `lookup` OR `read`). Opens no list/detail, no export, and NO menu node. | ### Action hierarchy — include prerequisite GRANTS This is a rule about GRANTS, not about which permissions exist — the permission ROWS of the floor exist by construction (see « Permission floor » below). When you grant an action to an actor, ALWAYS write its prerequisite grant lines for the SAME actor too: | If you grant… | You MUST also grant… | |---------------|------------------------| | `read` | `access` | | `create`, `update`, `delete` | `access` + `read` | | `export`, `import` | `access` + `read` | | `approve`, `reject` | `access` + `read` | | `assign`, `execute` | `access` + `read` | | `lookup` | *(nothing — autonomous by design: no `access`, no `read`)* | So an actor who can `create` gets three lines: `access`, `read`, `create`. `lookup` is the one action WITHOUT prerequisites — its whole point is serving FK dropdowns to actors who have neither the producer's menu nor its read surface. You normally never author it by hand anyway (see the derived block). ## Condition scopes (the **Portée** column) | Scope (write in the user's language) | Meaning | Runtime backing | |--------------------------------------|---------|-----------------| | `all` / `toutes` | All records in the target — admin-style (default) | Platform data-scope mechanism (`.read.all`) | | `own` / `les siennes` | Only records the actor created or owns | Platform data-scope mechanism (`DataScopePolicy` + `IOwnedEntity`) | | `assigned` / `attribuées` | Only records currently assigned to the actor | Platform data-scope mechanism (`DataScopePolicy` + `IAssignedEntity`) | | `team` / `équipe` | Records of the actor's team / direct reports | **Descriptive only** — materialization is planned with the HR application (the curated source of teams/managers, next chantier). Do NOT work around it by granting the producer's `read`. | | `custom` / `personnalisée` | Free-form — add a short clause in the cell describing the filter | Descriptive only — hand-written LINQ filter | There is **no `tenant` scope** — tenant isolation is mounted by construction, never modelled in the matrix: scaffold-entity mounts the named "Tenant" EF query filter per entity in ExtensionsDbContext (TENANT-FILTERS markers, audited by DEV-API-032). For a `custom` scope, write the filter description directly in the **Portée** cell (e.g. `région de l'utilisateur`). ### Scope materialization rule (`.read.all` pairing) `own`/`assigned`/`all` on a `read` map onto the platform's row-level data-scope mechanism (see `docs/architecture/data-scopes-rbac.md` in SmartStack.app): the entity's `{path}.read` permission is **scoped by default** (own ∪ assigned) and the sibling `{path}.read.all` permission grants global visibility. A module is **scoped** when at least one actor has a `read` whose Portée is NOT `all`/`toutes`. In a scoped module: 1. Every actor row `… .read` with Portée `all`/`toutes` MUST be accompanied by an extra row for the SAME actor: `… .read.all` (Portée `toutes`) — that is the permission that actually opens the global view at runtime. 2. Actor rows with Portée `own`/`assigned` keep the plain `… .read` line only — never grant them `.read.all` or a wildcard covering it. 3. In a NON-scoped module (every read is `all`), do NOT emit `.read.all` lines — the module simply doesn't opt into the data-scope mechanism. ### Reference rule (cross-module dropdowns — the producer's `lookup`) When an actor of module B needs module A's data only as REFERENCE data (FK dropdowns in its create/edit forms), the answer is the PRODUCER's `lookup` — never its `read`: - **Default — derived, not authored**: `derive-lookup-grants` (the colocated CLI, mandatory post-step of `/ba-create-data-model`) derives one `{producerApp}.{producerModule}.{producerSection}.lookup` row per (create/update actor × FK producer section) into the machine-owned block of the consumer module's `rbac.md`. You normally never write lookup rows by hand. - `lookup` opens ONLY the id+name reference surface (generated `/lookup` endpoints are gated `[RequirePermission(x.lookup, x.read)]`, ANY semantics) — no list/detail, no export, and NO menu visibility (`access` is the only action that reveals a nav node since SmartStack 3.62). - **Rich assignment surfaces** (filtered/decorated pickers): the consumer-side endpoint gated by the CONSUMER's permission remains the right tool (platform precedent: `assignable-roles` ← `… .assign`) — use it when the picker needs more than id+name. - **Granting the producer's `read`** stays an option for broad, ASSUMED cross-module needs only (document it in prose): since v3.62 it no longer leaks the producer into the menu, but it does open its whole read surface. See `docs/architecture/menu-vs-data-access.md` in SmartStack.app. ### Derived lookup block (machine-owned) The `derive-lookup-grants` CLI rewrites a machine-owned block at the end of the module's `rbac.md`, between `` and ``: - **Derivation** — the module entities' outgoing FKs (`*→1` / `1→1`, scope ≠ core) → producer section (list screen, else the entity's kebab-plural among the producer module's menu sections, else a `needsResolution` finding — NEVER a guess) × every consumer actor holding `create`/`update`. Actors already holding the producer section's `read`/`lookup` are skipped. - **The skip is INDIFFERENT to the Portée** — and that is deliberate, not an oversight. The row-level perimeter is an EF global query filter whose ONLY lift is `{path}.read.all` (`DataScopePolicy.ScopeAllPermission`); a derived `.lookup` grant does not lift it. So on a data-scoped producer the dropdown is filtered identically whether the grant is emitted or not — conditioning the skip on `own`/`assigned`/`team` would emit permissions that change NOTHING at runtime and re-create the redundancy the skip exists to remove. When a consumer genuinely needs the producer's whole reference surface and the producer is data-scoped, the missing piece is a `.read.all`, never a lookup grant. - **Suppressions are written down** — the block lists every skipped `(actor × producer section)` under the table, with which grant covers it, and an empty block distinguishes « aucune FK » from « tout était redondant ». Before that, the only trace was the CLI's stdout JSON. - **Paths in the block are app-qualified** (4 segments) — the ONE documented exception to prohibition #10. Phase 0 transcribes them verbatim, never re-prefixed. - **Never edit the block by hand** — re-run the CLI (it rewrites the block in full; the human matrix is untouched). Re-run after every `entité.md` change and after `/ba-reconcile-menu`. ```bash npx --prefer-offline tsx skills/business-analyse/create-rbac/cli/derive-lookup-grants/index.ts \ --spec '{"baRoot":".smartstack/ba","app":"","module":"","mode":"derive"}' ``` `/ba-audit-rbac` (RBAC-008) verifies the block's freshness via `"mode":"check"`. ## Permission floor (machine-owned — never author it) Every menu node gets a default permission FLOOR **by construction**: `scaffold-core-seed` (Phase 0 of `/ba-develop`) derives it from the nav tree it already seeds — the floor can never be forgotten, whatever the matrix says. Canonical definition (`lib/permission-actions.ts`, drift-locked): | Grain | Node | Floor permissions | |---|---|---| | Application | `{app}` | `access` | | Module | `{app}.{module}` | `access` | | Section | `{app}.{module}.{section}` | `access` `lookup` `read` `create` `update` `delete` `execute` | | Resource | `{app}.{module}.{section}.{resource}` | `access` `lookup` `read` `create` `update` `delete` `execute` | Consequences for what YOU author: - **The floor rows exist without you** — never write a permission line just so the permission "exists". A human row is a **GRANT**: it says which ACTOR holds the path (and with which Portée). - **What the human matrix carries**: the grants (actor × permission × portée) and the EXTRA actions outside the floor — `approve`, `reject`, `export`, `import`, `assign`, and the `.read.all` scope tier. - **Floor rows are seeded WITHOUT grants** — visible in the admin matrix, grantable by hand. The ONE exception is `access`: Phase 0 grandfathers it v3.62-style (a seeded role receives `{node}.access` iff it holds ≥ 1 permission UNDER the node; a `lookup` grant grandfathers nothing). - **Mirror block**: the colocated `derive-permission-floor` CLI writes a review mirror of the floor into the module's `rbac.md`, between `` (paths per node, never grants — the 2nd documented exception to prohibition #10). Run it after the matrix is written, and re-run after every menu change / `/ba-reconcile-menu`: ```bash npx --prefer-offline tsx skills/business-analyse/create-rbac/cli/derive-permission-floor/index.ts \ --spec '{"baRoot":".smartstack/ba","app":"","module":"","mode":"derive"}' ``` `/ba-audit-rbac` (RBAC-009) verifies the mirror's freshness via `"mode":"check"`. - **Reserved node codes**: a section or resource coded `read` or `all` breaks the `….read.all` scope-tier disambiguation of permission paths — the CLI warns, and the seed validator hard-errs. Rename the node in the menu. ## Standard roles & bundles (context — actors map to roles downstream) **The BA does NOT invent roles** — Phase 0 seeds ONE Role per project actor. Two things structure that mapping (shared reference: `_workflow/role-taxonomy.md`): - **Catégorie** (authored in `/ba-create-actors`): the actor's platform `RoleCategory` (`Admin | Manager | Contributor | Viewer | Custom`) — the seeded role carries it; absent/unknown → `Custom`. `Global` is reserved for platform roles (`superadmin` / `platformadmin` / `user`) and never authored by the BA. - **Standard bundles** (opt-in, offered by `/ba-create-actors`): the three per-app bundles « Administration {App} » (Admin), « Gestion {App} » (Contributor), « Consultation {App} » (Viewer). When the user opted in, write their default rows deterministically in each module matrix: **admin** = every action of the module (+ `.read.all` in scoped modules) ; **operator** = `access`, `read`, `create`, `update` (+ `.read.all` per the materialization rule when its read is `toutes`) ; **viewer** = `access`, `read`. `lookup` rows stay DERIVED — the CLI covers bundles like any other create/update actor. ## Seed transcription — `derive-rbac-grants` (the matrix never travels by hand) The colocated `cli/derive-rbac-grants/` CLI is the DETERMINISTIC transcription of the matrices into the seed's RBAC fragment — `/ba-develop` Phase 0 invokes it and pastes its output verbatim instead of re-typing rows (the historical silent-loss point): ```bash npx --prefer-offline tsx skills/business-analyse/create-rbac/cli/derive-rbac-grants/index.ts \ --spec '{"baRoot":".smartstack/ba","mode":"derive"}' ``` - Parses every module's `rbac.md` (human rows + derived-lookups block) and each app's `acteur.md`; app-prefixes the module-scoped human rows, transports derived rows **verbatim**, skips the floor, and grandfathers the v3.62 `.access` rows — emitting per-app `actors[]` / `permissions[]` (authored, non-floor) / `rolePermissions[]`. - **Role identity rule** (deterministic): the seeded role is `code = slugifyRoleCode(actor label)`, `name = actor label` verbatim, `category` from **Catégorie** via `_workflow/role-taxonomy.md`. Two actors slugging to the same code is a `role-code-collision` to resolve in `acteur.md` — never merged silently. - **Never guesses**: an unknown actor code, an unparsable path or a matrix without its `acteur.md` lands in `needsResolution[]` — fix the BA docs and re-run; no row is dropped or invented silently. - `"mode":"check"` (with `"projectPath"`) compares the fresh derivation to the SEEDED state (`.smartstack/core-seed/*.state.json`) in BOTH directions — `missing-grant` (a specified right not seeded) and `extra-grant` (a seeded right no BA row explains). Drift is DATA (exit 0); the verdict belongs to `audit-dev-core` **DEV-CORE-011**. ## Decision table Read the module's `rbac.md` and the menu tree, then match the row and follow the indicated file. After every Write, re-read and re-enter the table. | State (for module M in app X) | Phase | Follow | |-------------------------------|-------|--------| | No menu tree | — | Defer to `/ba-create-menu` | | No module pinned yet (session start, request names none unambiguously) | — | Run **§ Scope selection** — application → module — before anything else | | No actors in `/acteur.md` | — | Defer to `/ba-create-actors` | | Module M has no permissions yet | 1 | `levels/discovery.md` | | M has module-level permissions only | 2 | `levels/detail.md` | | All sections of M have detailed permissions | 3 | `levels/review.md` | | M reviewed + self-check clean | — | Hand off to `/ba-create-data-model` | | User asks to refine or remove a permission | — | Adjust + re-Write `rbac.md` | | User asks to add or modify ONE row on a module already developed | — | Route to `/ba-change` (kind=permission) — actor / path / Portée validated against the closed vocabularies, reach + duties checked, derived blocks re-checked, the DEV-CORE-011 seed-parity re-entry named | | User asks a question without changing anything | — | Answer in prose, no Write | The workflow is **per-module**: each module goes through Phases 1 → 2 → 3 independently. Within a module you progress from broad-stroke access (discovery) to per-section detail, then a completeness review. ## Self-check before writing (RBAC → data-model gate) Before handing off, do a quick self-check on the module matrix you wrote — do NOT produce audit findings here (the deep audit is `/ba-audit-rbac`, which reads the tree and writes its verdict): - Every actor referenced exists in `/acteur.md` (Grep the code). - Every permission uses a verb from the 12-value vocabulary. - Action hierarchy holds: no `read` without `access`, no `create`/`update`/ `delete`/`export`/`import`/`approve`/`reject`/`assign`/`execute` without `access` + `read` (`lookup` alone is legal — and normally machine-derived). - Every UC primary actor has at least the actions implied by its main flow. - No `external` actor has `delete` or `execute` without explicit user confirmation. - No segregation-of-duties slip you missed (same actor with both `create` and `approve` on the same target — flag it, don't silently keep it). - No hand-written row inside either machine-owned block (`ba:rbac-derived-lookups`, `ba:rbac-floor`) — and no human row written ONLY to make a floor path "exist" (a human row is a grant; the floor rows exist by construction). - No section/resource coded `read` or `all` in the menu (reserved — breaks the `….read.all` scope-tier grammar). Surface any gap to the user instead of writing a half-defined matrix. The deeper audit (RBAC-001..010 — minimum perms, SoD, coverage, derived-lookup + floor freshness) belongs to `/ba-audit-rbac`. ## After writing → hand off to the data model Acknowledge in one line ("Matrice RBAC définie pour PIPELINE — 3 acteurs."). Per the fixed phase order, the next phase is the **data model** — propose continuing with `/ba-create-data-model` (don't ask "what next?"). Refresh the App-level `rbac.md` rollup pointer when you finish a module, and convert any descendant `rbac.md` placeholders **of the pinned module** into the one-line inheritance pointer — never fan out across the whole tree. ## Absolute prohibitions 1. **Never use an action outside the 12-value vocabulary** — fold any user verb into one. 2. **Never reference an actor not in `/acteur.md`** — defer to `/ba-create-actors`. 3. **Never reference a target (module/section/resource) not in the menu tree** — defer to `/ba-create-menu`. 4. **Never fabricate, abbreviate, or transform codes** — copy them verbatim from `acteur.md` / the folder names. Grep to confirm before using. 5. **Never skip phases**: discovery → detail → review, per module. 6. **Never write a permission without its prerequisites** — `create` implies `access` + `read`. 7. **Never set a `custom` scope without a filter clause** in the Portée cell. 8. **Never duplicate the same `(actor, target, action)` line** in one matrix. 9. **Never grant `delete` or `execute` to `external` actors** without explicit user confirmation. 10. **Never write the app prefix into the permission segments** — author `module.section.action` (section) or `module.section.resource.action` (resource); the app prefix is added at the page/controller boundary later. TWO exceptions, both machine-owned and never written by you: the derived-lookups block (`derive-lookup-grants`) and the permission-floor mirror block (`derive-permission-floor`) carry app-qualified paths. 11. **Never duplicate the module matrix into section/resource `rbac.md`** — those inherit (one-line pointer) and only refine when there is a genuine difference. 12. **Never Write a path outside the selected application** — every Write lands under `.smartstack/ba//`; re-check the pinned scope before every Write. Another application's `rbac.md` is reported on overlap, never edited. ## Per-phase guidance Load the level file that matches the decision table for the detailed proposal heuristics: - `levels/discovery.md` — broad-stroke access per module (Phase 1). - `levels/detail.md` — refine per section with actions + scopes (Phase 2). - `levels/review.md` — completeness + SoD review for the module (Phase 3).