@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/create-rbac/SKILL.md

@@ -0,0 +1,255 @@
+---
+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: reads the menu tree, actors, use cases and
+  rules, proposes coverage per actor × action, asks the user to validate, then
+  writes the file. Run after business rules (`/ba-create-business-rules`), before
+  the data model (`/ba-create-data-model`).
+allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
+---
+
+# 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 |
+
+## 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/<APP>/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/<APP>/<MODULE>/use-case.md` (and each section's
+     `use-case.md`) for primary/secondary actors + main-flow steps.
+   - Read `.smartstack/ba/<APP>/<MODULE>/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 `<baRoot>/<APP>/<MOD>/<sec-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/<APP>/<MODULE>/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 `<!-- ba:rollup auto -->`). 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
+<!-- ba:rbac level=module code=PIPELINE -->
+# RBAC — CRM / PIPELINE
+
+| Acteur | Permission (`module.section[.resource].action`) | Portée |
+|--------|------------------------------------------|--------|
+| BA-001-AC-001 (Commercial) | `crm.pipeline.opportunites.read` | toutes |
+| BA-001-AC-001 (Commercial) | `crm.pipeline.opportunites.create` | les siennes |
+| BA-001-AC-002 (Manager commercial) | `crm.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).
+
+### 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`).
+
+## Action vocabulary (11 exact values — mirror the PermissionAction enum)
+
+`access` | `read` | `create` | `update` | `delete` | `export` | `import`
+| `approve` | `reject` | `assign` | `execute`
+
+**Never invent other actions.** Fold any user verb into one of these.
+
+| Action | Meaning |
+|--------|---------|
+| `access` | Navigate to the menu node (visibility) |
+| `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.) |
+
+### Action hierarchy — include prerequisites
+
+When you grant an action, ALWAYS write its prerequisite lines too:
+
+| If you grant… | You MUST also include… |
+|---------------|------------------------|
+| `read` | `access` |
+| `create`, `update`, `delete` | `access` + `read` |
+| `export`, `import` | `access` + `read` |
+| `approve`, `reject` | `access` + `read` |
+| `assign`, `execute` | `access` + `read` |
+
+So an actor who can `create` gets three lines: `access`, `read`, `create`.
+
+## Condition scopes (the **Portée** column — translates to a LINQ filter later)
+
+| Scope (write in the user's language) | Meaning |
+|--------------------------------------|---------|
+| `all` / `toutes` | All records in the target — admin-style (default) |
+| `own` / `les siennes` | Only records the actor created or owns |
+| `team` / `équipe` | Records of the actor's team / direct reports |
+| `custom` / `personnalisée` | Free-form — add a short clause in the cell describing the filter |
+
+There is **no `tenant` scope** — tenant isolation is automatic at runtime via
+`TenantId`. For a `custom` scope, write the filter description directly in the
+**Portée** cell (e.g. `région de l'utilisateur`).
+
+## Standard roles (context — actors map to roles downstream)
+
+The SmartStack runtime uses 4 standard roles per app: `admin` (full CRUD +
+wildcard), `manager` (CRU), `contributor` (CR), `viewer` (R), plus global
+`superadmin` / `platformadmin` / `user`. **The BA does NOT invent roles** — it
+uses the project actors directly. A downstream scaffold step maps each actor to
+standard roles based on the granted actions.
+
+## 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 actors in `<APP>/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 add/remove/refine a permission | — | Adjust + re-Write `rbac.md` |
+| 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 `<APP>/acteur.md` (Grep the code).
+- Every permission uses a verb from the 11-value vocabulary.
+- Action hierarchy holds: no `read` without `access`, no `create`/`update`/
+  `delete`/`export`/`import`/`approve`/`reject`/`assign`/`execute` without
+  `access` + `read`.
+- 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).
+
+Surface any gap to the user instead of writing a half-defined matrix. The deeper
+audit (RBAC-001..005 — minimum perms, SoD, coverage) 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 you encounter into the one-line inheritance pointer.
+
+## Absolute prohibitions
+
+1. **Never use an action outside the 11-value vocabulary** — fold any user verb
+   into one.
+2. **Never reference an actor not in `<APP>/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.
+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.
+
+## 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).

package/templates/skills/business-analyse/create-rbac/levels/detail.md

@@ -0,0 +1,86 @@
+---
+phase: permissions
+kind: level
+level: detail
+---
+
+# Phase 2: DETAIL — refine permissions per section
+
+> Follow this file when the decision table in `SKILL.md` routes here. The action
+> vocabulary, scopes and authority rules live in `SKILL.md`.
+
+## Goal
+
+Refine the module matrix to **section level** with specific actions and condition
+scopes. Walk through each section of module M that has use cases or business
+rules.
+
+## Before proposing (for each section S) — read the tree
+
+1. Read `<APP>/<MODULE>/<section>/use-case.md` (or the module `use-case.md`
+   filtered to S) — extract the main-flow steps.
+2. For each UC in S, identify the primary actor + the main-flow actions using the
+   verb mapping below.
+3. Read `<APP>/<MODULE>/règles-métier.md` — note any rule whose scope implies an
+   access permission on S.
+4. Read the module's `rbac.md` — what is already refined for S?
+
+## UC verb → permission action mapping
+
+Read the main-flow step descriptions and fold each verb into one action:
+
+| UC verb pattern | Action |
+|-----------------|--------|
+| "views", "consults", "searches", "browses" | `read` |
+| "creates", "submits", "adds", "registers" | `create` |
+| "edits", "modifies", "updates", "changes" | `update` |
+| "deletes", "removes", "archives", "cancels" | `delete` |
+| "exports", "downloads", "generates report" | `export` |
+| "imports", "uploads", "bulk loads" | `import` |
+| "approves", "validates", "confirms" | `approve` |
+| "rejects", "refuses", "declines" | `reject` |
+| "assigns", "delegates", "transfers" | `assign` |
+| "triggers", "executes", "runs", "activates" | `execute` |
+
+For each UC, the **primary actor** must receive at minimum the actions implied by
+its main flow (plus prerequisites — see the action hierarchy in `SKILL.md`). In
+your prose, anchor each line to the UC code that justifies it.
+
+## Business-rules cross-reference
+
+Scan `règles-métier.md` for rules targeting S. A rule that gates access (e.g. "a
+remise > 20 % requires manager approval") implies the corresponding actor needs
+the `approve` action on S — reference the `BR-…` code in your prose.
+
+## Scope defaults per actor type (the Portée column)
+
+| Actor type | Default scope | Rationale |
+|------------|---------------|-----------|
+| Internal admin-type | `all` / toutes | Full visibility on all records |
+| Internal contributor-type | `own` for create/update, `all` for read | Sees own work, reads everything |
+| Manager-type | `team` for read, `own` for create | Sees the team's work, creates own |
+| External actors | `own` ALWAYS | External users only see their own data |
+
+These are **defaults** — override from the UC context or the user's request, and
+ask the user (via AskUserQuestion) to confirm any non-obvious scope choice.
+
+## Propose — section by section
+
+Describe the refined lines in prose (actor, actions, scope, justifying UC/rule),
+then ask the user to validate via **AskUserQuestion** (one multi-select per
+section, or one confirmation if the inference is unambiguous).
+
+## After the user validates → Write the matrix
+
+1. Acknowledge briefly (one sentence).
+2. **Write** `<APP>/<MODULE>/rbac.md` with the section-level lines added, using
+   permissions `module.section[.resource].action` — 3 segments for a section
+   (e.g. `pipeline.opportunites.create`), 4 for a resource (e.g.
+   `pipeline.opportunites.devis.create`). Re-list every line that must survive — the
+   Write overwrites the file, including the Phase 1 module lines you keep.
+3. Announce the next section, or the transition to Phase 3 (review).
+
+## Transition (Phase 2 → Phase 3)
+
+When every section of M that has use cases is refined, move to Phase 3 (follow
+`levels/review.md`) for the module-level completeness review.

package/templates/skills/business-analyse/create-rbac/levels/discovery.md

@@ -0,0 +1,63 @@
+---
+phase: permissions
+kind: level
+level: discovery
+---
+
+# Phase 1: DISCOVERY — broad-stroke access per module
+
+> Follow this file when the decision table in `SKILL.md` routes here. The action
+> vocabulary, scopes and authority rules live in `SKILL.md`.
+
+## Goal
+
+Establish broad-stroke access: which actors can reach module M in app X, at the
+module level (`module.access` / `module.read`), before refining per section.
+
+## Before proposing — read the tree
+
+1. `Glob .smartstack/ba/**/index.md` — list every module in app X.
+2. Read `<APP>/acteur.md` — the actors with their `BA-…-AC-…` codes and types
+   (`internal` / `external` / `system`). Grep a code to confirm it exists.
+3. Read `<APP>/<MODULE>/use-case.md` (+ each section's `use-case.md`) — identify
+   the primary/secondary actors per module.
+4. Read the module's existing `rbac.md` — anything already defined?
+
+## UC cross-reference — infer minimum access
+
+For module M, scan its use cases. Every UC's **primary actor** must get at least
+`access` + `read` on M. In your prose, justify each line with the UC code that
+implies it. Actors not referenced by any UC for M may still be proposed from
+their type:
+
+- `internal` admin-type actors → `access` + `read` on the module (often broader).
+- `external` actors → `access` only, usually at application level (their portal).
+- `system` actors → `access` + `read` + `execute` on the relevant modules.
+
+## Propose — one AskUserQuestion per module
+
+Describe the candidates in prose, then ask via **AskUserQuestion** (one
+multi-select per module) which actors should access the module. Pre-select the
+actors inferred from use cases and note the justification next to each. Open
+exploration questions (cross-region isolation, who owns approvals) go in prose,
+not in the closed choice.
+
+## After the user validates → Write the matrix
+
+1. Acknowledge briefly (one sentence).
+2. **Write** `<APP>/<MODULE>/rbac.md` with the module-level lines, re-listing
+   every line that must survive (the Write overwrites the file). Use the
+   `rbac.md` skeleton from `SKILL.md`: module-level permissions `module.action`
+   (e.g. `pipeline.access`, `pipeline.read`), scope in the Portée column.
+   Section-level permissions add the section segment in Phase 2.
+3. Announce the next module, or the transition to Phase 2 (detail) for this
+   module's sections.
+
+Module-level discovery lines look like `module.access` and `module.read` (no
+section segment yet). Phase 2 adds the section segment and the specific actions.
+
+## Transition (Phase 1 → Phase 2)
+
+When module M has broad-stroke access for every validated actor, move to Phase 2
+for M's sections (follow `levels/detail.md`). When every module in app X has
+broad-stroke access, Phase 1 is complete for X.

package/templates/skills/business-analyse/create-rbac/levels/review.md

@@ -0,0 +1,66 @@
+---
+phase: permissions
+kind: level
+level: review
+---
+
+# Phase 3: REVIEW — validate the module matrix
+
+> Follow this file when the decision table in `SKILL.md` routes here. The action
+> vocabulary, scopes and authority rules live in `SKILL.md`.
+
+## Goal
+
+Validate the complete RBAC matrix for module M. Catch gaps, over-privilege and
+segregation-of-duties slips before handing off to the data model.
+
+## Completeness checklist — verify before marking M complete
+
+- [ ] The module has at least one actor with `access` + `read`.
+- [ ] Every section with use cases has lines matching its UC primary actors.
+- [ ] No section is unreachable (zero actors with `access`).
+- [ ] Every UC primary actor has actions matching its main-flow verbs for that
+      section.
+- [ ] No `external` actor has `delete` or `execute` (challenge the user if found).
+- [ ] No segregation-of-duties violation: the same actor must NOT hold both
+      `create` and `approve` on the same target.
+- [ ] Every `custom` scope cell carries a concrete filter clause.
+- [ ] Action hierarchy holds: no `read` without `access`, no `create`/`update`/
+      `delete`/… without `access` + `read`.
+
+## Present the matrix for validation
+
+Summarize the module matrix in prose, grouped by actor (targets + actions +
+scope, compact). Then ask the user to validate via **AskUserQuestion** with
+closed choices, e.g.:
+
+- *Matrix is correct — proceed*
+- *Add / remove actions for a specific actor + target*
+- *Change the scope for a specific actor + target*
+- *Other adjustment* (describe in prose)
+
+## Detect and fix gaps
+
+If the checklist flags an issue, report it in prose before validating:
+
+- **Unreachable section**: "Section `dashboard` has no actor with `access`. Grant
+  `access` + `read` to the manager actor?"
+- **Over-privilege**: "The external candidate actor has `delete` on the portal.
+  External actors should not delete — remove it?"
+- **SoD violation**: "The commercial actor holds both `create` and `approve` on
+  `opportunites`. Split approval to the manager actor?"
+
+When the user confirms a fix, re-Write `rbac.md` with the corrected lines
+(re-list every line that must survive).
+
+## After review → hand off
+
+Once the matrix is validated (or corrected), run the **light self-check** in
+`SKILL.md` (vocabulary, hierarchy, actor existence, SoD), surface any residual
+gap, then hand off to the data model (`/ba-create-data-model`). The **deep
+audit** (RBAC-001..005) is `/ba-audit-rbac`, which reads the tree and writes its
+own verdict — do not produce audit findings here.
+
+Refresh the App-level `rbac.md` rollup pointer to include this module, and leave
+section/resource `rbac.md` as inheritance pointers unless a genuine refinement
+exists.