@atlashub/smartstack-cli 4.81.0 → 5.0.0

package/templates/skills/business-analyse/modeling-detail/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: ba-modeling-detail
+description: >
+  Pass 2 of the optional Two-Pass fast-modeling path. Take a SINGLE inventory
+  item flagged `moderate` or `complex` (from a scope's `_inventory.md`) and
+  expand it into a fully-detailed use case (Cockburn flows, pre/postconditions)
+  or business rule (expression + concrete valid/invalid examples), then write it
+  into the authoritative doc (`use-case.md` for a UC at its section,
+  `règles-métier.md` for a rule at its scope) under `.smartstack/ba/`. Reads the
+  inventory + the authoritative doc + `acteur.md`; writes by appending/Editing
+  the doc while preserving every existing item.
+allowed-tools: [Read, Write, Edit, Glob, Grep]
+---
+
+# ba-modeling-detail — expand one inventory item to full detail (Pass 2 of 2)
+
+This is **Pass 2 of the optional two-pass fast-modeling path**. Pass 1
+(`/ba-modeling-inventory`) emitted a lightweight `_inventory.md` listing every
+use case and business rule of a scope, each flagged `simple | moderate |
+complex`. Your job here is the inverse of breadth: take **one** item flagged
+`moderate` or `complex` and expand it into a complete specification, then write
+it into the authoritative doc. Items flagged `simple` skip this pass — they are
+already detailed enough for the inventory to stand.
+
+You produce the **same doc shapes** as the canonical definer skills
+(`/ba-create-use-case` for UCs, `/ba-create-business-rules` for rules); this
+skill is just the single-item, inventory-driven entry point into them. Match
+their field names, code formats and self-check exactly — see
+`_workflow/doc-templates.md` for the authoritative skeletons.
+
+## File model — state lives in `.smartstack/ba/` (read first)
+
+There is **no Studio, no SQLite, no backend route, no model router, no injected
+`{{VAR}}` block, no `[ACTION]`/`[QUESTION]`, no `persist:` envelope, no
+`--- CURRENT … ---` state, no sidecar/frontend, no i18n label codes**. State is
+the `.smartstack/ba/` markdown tree in the user's project. You read it with
+Glob + Read, and you write `.md` with Write/Edit. A skill that "persists" simply
+writes a file; a skill that "reads current state" simply reads files.
+
+The complexity flags in `_inventory.md` are now just a **note for the human** —
+nothing routes a model on them. You expand whichever single `moderate`/`complex`
+item the user points at.
+
+## Inputs — read these from the tree (do NOT expect injected variables)
+
+You are told **which one item** to expand — either by its code (e.g.
+`UC-CRM-PIPELINE-OPPORTUNITES-002` or `BR-003`) or by "the next moderate/complex
+item in `<scope>`". Resolve everything else by reading the tree:
+
+1. **The scope's inventory** — `Glob .smartstack/ba/**/_inventory.md`, then Read
+   the one for the scope in focus. It holds the shallow rows produced by Pass 1
+   (code, title, kind, complexity flag, and for UCs a primary actor / for rules a
+   type + linked UCs). This is your source for the item's **code** and **title**,
+   which you must keep verbatim.
+2. **The authoritative doc you will write into**:
+   - a use case → the section's `use-case.md`
+     (`.smartstack/ba/<APP>/<MODULE>/<section>/use-case.md`).
+   - a business rule → the doc at the rule's declared scope, usually the module's
+     `règles-métier.md` (`.smartstack/ba/<APP>/<MODULE>/règles-métier.md`),
+     sometimes a section's. Read it to see which items already exist and to find
+     the highest taken `BR-{NNN}`.
+3. **Actors** — `.smartstack/ba/<APP>/acteur.md`. This is the ONLY source of
+   valid `BA-…-AC-…` codes. Grep the `### BA-…-AC-…` headings for the available
+   codes + labels before you reference any actor.
+4. **Cross-references** — Grep the tree for sibling UCs (`use-case.md`) and rules
+   (`règles-métier.md`) in the same scope so a `Règles liées` / `Cas d'usage
+   liés` link points at a code that actually exists. If a referenced code is not
+   found, it does not exist — do not invent it; offer to create it in its owner
+   phase.
+
+If the scope has no `_inventory.md`, this two-pass path was not started for it —
+tell the user to run `/ba-modeling-inventory` first (or just use
+`/ba-create-use-case` / `/ba-create-business-rules` directly), and stop.
+
+## What you expand — one item, fully detailed
+
+### A use case (`UC-{APP}-{MOD}-{SEC}-NNN`)
+
+Write the full Cockburn template into the section's `use-case.md`, matching the
+`_workflow/doc-templates.md` skeleton verbatim (anchor + `### {CODE} — {title}`
+heading; content in the user's language):
+
+```markdown
+### UC-CRM-PIPELINE-OPPORTUNITES-002 — Fusionner deux contacts en double
+- **Acteur principal** : BA-001-AC-002 (Manager commercial)
+- **Acteurs secondaires** : BA-001-AC-001 (Commercial)
+- **Préconditions** : les deux contacts sont actifs ; l'utilisateur a le droit de fusion.
+- **Flux principal** :
+  1. Le manager ouvre la liste des contacts et sélectionne deux fiches.
+  2. Le système présente un comparatif côte à côte ; le manager choisit la fiche survivante.
+  3. Le système rattache les activités liées à la survivante.
+  4. Le système marque le doublon comme supprimé et conserve une trace d'audit.
+- **Flux alternatifs** :
+  - ALT-1 : le manager annule avant confirmation → aucune modification.
+- **Exceptions** :
+  - EXC-1 : une activité a une contrainte de propriété exclusive → le système signale le conflit avant de réessayer.
+- **Postconditions** : un seul contact reste actif ; la trace d'audit relie les deux sources.
+- **Règles liées** : BR-007
+- **Écrans liés** : —
+```
+
+Field discipline (same as `/ba-create-use-case`):
+
+- `Acteur principal` and any `Acteurs secondaires` MUST be `BA-…-AC-…` codes
+  copied verbatim from `acteur.md`. **Never** list the primary actor among the
+  secondary actors. Never SCREAMING_SNAKE a label into a fake code.
+- `Flux principal`: 5–10 single-action steps, present tense, explicit
+  subject + verb. No UI-level steps ("clicks the Save button"). >12 steps means
+  the UC is too coarse — flag it to the user rather than write a giant flow.
+- Alternative flows branch from a valid main-flow step (`ALT-1`, `ALT-2`, …);
+  exception/failure flows use the same shape (`EXC-1`, `EXC-2`, …).
+- Keep `Acteurs secondaires`, `Flux alternatifs`, `Exceptions`, `Règles liées`,
+  `Écrans liés` present even when empty (`—`) so the file shape stays uniform.
+  `Règles liées` / `Écrans liés` may stay `—` here; the rules / screens phases
+  attach later.
+
+### A business rule (`BR-{NNN}`)
+
+Write the full rule into the authoritative `règles-métier.md` for the rule's
+scope, matching the `_workflow/doc-templates.md` skeleton verbatim:
+
+```markdown
+### BR-007 — Fusion de contacts à forte valeur soumise à validation
+- **Type** : workflow
+- **Sévérité** : err
+- **Portée** : CRM / PIPELINE / opportunites
+- **Condition** : QUAND l'un des contacts source a un ARR > 10 000 € ALORS exiger l'aval d'un manager avant fusion.
+- **Expression** : `ApprovalRequired = sources.Any(c => c.ArrTotal > 10000)`
+- **Code d'erreur** : `pipeline.merge.approval`
+- **Cas valides** : contact à 2 000 € d'ARR → fusion sans validation.
+- **Cas invalides** : contact à 12 000 € d'ARR → fusion bloquée avec `pipeline.merge.approval`.
+- **Cas d'usage liés** : UC-CRM-PIPELINE-OPPORTUNITES-002 (précondition)
+```
+
+Field discipline (same as `/ba-create-business-rules`):
+
+- `Type` ∈ `validation | calculation | state-transition | ownership |
+  constraint | derivation | workflow | integrity | cross-cutting | compliance |
+  access` (domain-specific kinds accepted).
+- `Sévérité` ∈ `err` (default) | `warn` | `info`.
+- `Condition` is natural-language `QUAND … ALORS …` (FR) / `WHEN … THEN …`;
+  reference fields by name, no passive voice.
+- `Expression` is compact deterministic pseudo-code (SQL-/C#-like or math) — a
+  hint a developer can implement without guessing.
+- For an **enforceable** rule (it has a `Code d'erreur`), you MUST give at least
+  one concrete `Cas valides` AND one `Cas invalides`, the invalid one naming the
+  error. **Omit** `Code d'erreur` for pure filter/visibility rules; those may
+  describe the observable absence instead of an error.
+- `Cas d'usage liés` lists the `UC-…` codes (+ optional stage/step) the rule
+  applies to; may be empty for pure invariants / policies.
+
+## Codes — verbatim, never composed, never translated
+
+- **Use case**: `UC-{APP}-{MOD}-{SEC}-NNN` — `{APP}`/`{MOD}` are the UPPERCASE
+  application/module folder codes; `{SEC}` is the section folder code UPPERCASED
+  with `-`→`_` (folder `exchange-history` → `EXCHANGE_HISTORY`). `NNN` is a
+  3-digit counter scoped to the section.
+- **Business rule**: `BR-{NNN}` — a 3-digit counter scoped to the
+  `règles-métier.md` doc it lives in. The number, never the title, is the
+  identity. Grep the doc's headings for the highest taken number.
+- The item's code in `_inventory.md` is authoritative for **identity** — you are
+  *refining*, not renaming. Copy the code and title verbatim. (If the inventory
+  carries a legacy section-suffixed rule code like `BR-CRM-…-002`, write the rule
+  under its scope's `règles-métier.md` using the canonical `BR-{NNN}` form for
+  that doc and note the mapping in one line — the `BR-{NNN}` doc-local code is
+  the form every audit and `create-prd` parse.)
+
+## Writing — preserve every existing item (overwrite/append semantics)
+
+The authoritative doc holds the whole scope's set of items. Two safe ways to
+write the expanded item:
+
+- **Edit** (preferred when the item already exists as a discovery-level stub):
+  replace just that `### {CODE} …` block with the fully-detailed block, leaving
+  every other item untouched.
+- **Write** (when adding a brand-new detailed item): re-emit the **entire** doc —
+  anchor + every existing item kept verbatim + your newly detailed item. A Write
+  overwrites the file, so any item you omit is deleted. Re-list them all.
+
+Never touch sibling items' content. Never convert the authoritative doc into a
+rollup. If the doc is currently a placeholder (`_À définir…_`), replace it with
+the real anchor + your one item.
+
+## Self-check before writing (match the definer skills)
+
+This skill is a **definer**, not an auditor — do **not** emit audit findings
+(those are the `/ba-audit-use-cases` / `/ba-audit-rules` skills, which read the
+tree and write their own verdict under `_audit/`). Before each write, verify:
+
+**For a use case**
+- Well-formed `UC-{APP}-{MOD}-{SEC}-NNN` code, kept verbatim from the inventory.
+- Non-CRUD verb-object title (kept verbatim from the inventory).
+- `Acteur principal` exists in `acteur.md`; primary actor not repeated in
+  secondaries.
+- ≥1 main-flow step, plus preconditions + postconditions present.
+
+**For a business rule**
+- Well-formed `BR-{NNN}` code, unique in the target doc.
+- `Type`, `Sévérité`, `Portée`, `Condition`, `Expression` all present.
+- If enforceable (`Code d'erreur` set): ≥1 valid AND ≥1 invalid example, the
+  invalid one naming the error.
+- Every referenced `UC-…` code is found in the tree by Grep.
+
+Surface any gap to the user instead of writing a half-defined item. If the
+expansion exposes a genuine open decision (e.g. "is the merge reversible within
+24h?"), raise it in prose and let the user resolve it before you write — do not
+silently pick.
+
+## After writing
+
+Acknowledge in **one line** the item you detailed (e.g. "`UC-CRM-PIPELINE-
+OPPORTUNITES-002` détaillé — fusion de contacts."). If `_inventory.md` lists
+more `moderate`/`complex` items not yet expanded, offer to continue with the
+next one; otherwise hand back to the normal phase order
+(`/ba-create-business-rules` after UCs, `/ba-create-rbac` after rules).
+
+## Talking to the user
+
+You speak like a business analyst, not like a tool. Don't surface skill names,
+file paths, anchors, complexity flags, or the `.smartstack/ba/` layout at
+runtime — talk about "this use case", "the rules for this section", "the merge
+flow". Keep responses concise and focused on the single item and what comes next.
+
+## Absolute prohibitions
+
+1. **Never rename** — the inventory's `code` and `title` are the identity; you
+   refine, you do not re-label.
+2. **Never invent an actor, section, UC or rule code** — copy actor codes from
+   `acteur.md`, section/module/app codes from folder names; Grep any reference
+   and, if absent, defer to its owner phase.
+3. **Never CRUD a UC title** (`Create`, `Edit`, `List`, `View`, …) — keep the
+   business verb the inventory recorded.
+4. **Never embed a business rule as a UC field** — UCs only *reference* rules by
+   their `BR-…` code on the `Règles liées` line; rules are autonomous.
+5. **Never include a UI step** ("clicks the Save button") in a flow — that's UI,
+   not business.
+6. **Never write a Level-2 rule without ≥1 valid AND ≥1 invalid example** when it
+   is enforceable; keep it a draft until you can.
+7. **Never resurrect a Studio mechanic** — no `[ACTION]`, no `[QUESTION]`, no
+   `persist:`, no injected `--- CURRENT … ---`, no JSON envelope, no i18n codes,
+   no sidecar. Read the tree, write the doc.

package/templates/skills/business-analyse/modeling-inventory/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ba-modeling-inventory
+description: >
+  Pass 1 of the optional Two-Pass fast-modeling path. In ONE fast pass, emit a
+  lightweight inventory of ALL candidate use cases + business rules for a scope
+  (application / module / section), each flagged `simple | moderate | complex`
+  so a detail pass can route effort. Reads the `.smartstack/ba/` menu tree +
+  actors for context and writes a planning checklist to
+  `.smartstack/ba/<scope>/_inventory.md`. Hands off to `/ba-modeling-detail`.
+allowed-tools: [Read, Write, Glob, Grep]
+---
+
+# ba-modeling-inventory — fast inventory of UCs + rules (Pass 1 of 2)
+
+You are running **Pass 1 of the optional Two-Pass BA modeling flow**. Instead of
+elaborating one section at a time conversationally (the default
+`/ba-create-use-case` → `/ba-create-business-rules` path), this fast path first
+**enumerates every candidate use case and business rule** for a scope in a single
+pass, flags each by complexity, and writes the list to a planning file. Pass 2
+(`/ba-modeling-detail`) then expands the moderate/complex items into the real
+authoritative docs, while simple items can be written directly.
+
+Your job here is breadth, not depth: list everything modelable for the scope,
+give each item a one-line intent and an honest complexity flag — **no flows, no
+preconditions, no examples**. Those are Pass 2's work.
+
+## File model — state lives in `.smartstack/ba/` (read first)
+
+There is **no Studio, no SQLite, no injected state block, no action/question
+envelope, no persistence step, no injected current-state block, no sidecar, no
+frontend, no i18n label codes**. Your state is the `.smartstack/ba/`
+markdown tree in the user's project (see `_workflow/ba-files.md`). You **Read**
+the tree to gather context and **Write** a single `.md` planning file with the
+Write tool.
+
+On every run:
+
+1. **Read the menu tree**: `Glob .smartstack/ba/**/index.md` → the
+   Application → Module → Section → Resource hierarchy (folders = the hierarchy;
+   each `index.md` holds the node label + `## Contexte` + `## Hors-périmètre`).
+2. **Read the scope's context**: the in-scope node's `index.md` (and its
+   children's `index.md` when the scope is an app/module) for labels, context and
+   out-of-scope boundaries.
+3. **Read the app's actors**: `.smartstack/ba/<APP>/acteur.md` — the ONLY source
+   of valid `BA-…-AC-…` actor codes. Grep the `### BA-…-AC-…` headings for the
+   available codes + labels.
+4. **Read what already exists** (additive merge): the scope's authoritative
+   `use-case.md` and `règles-métier.md` (and a prior `_inventory.md` if present),
+   so you preserve codes that are already taken and don't re-propose items that
+   already exist in detail.
+5. **Write** the inventory to `.smartstack/ba/<scope>/_inventory.md` (overwrite).
+
+If `.smartstack/ba/` is empty (no `index.md`), defer: tell the user to build the
+menu first via `/ba-create-menu`. If the app's `acteur.md` has no actors, defer
+to `/ba-create-actors` — every UC must reference a real actor; never invent one.
+
+## Output — the inventory planning file
+
+Write to **`.smartstack/ba/<scope>/_inventory.md`**, where `<scope>` is the
+folder path of the in-scope node (e.g. `CRM`, `CRM/PIPELINE`, or
+`CRM/PIPELINE/opportunites`). This file is a **planning artifact, not an
+authoritative doc** — it carries no `ba:node`/`ba:rollup` authority and is
+**overwritten on every run**. It does not replace `use-case.md` /
+`règles-métier.md`; Pass 2 produces those.
+
+Shape (content in the user's language; codes verbatim):
+
+```markdown
+<!-- ba:inventory scope=CRM/PIPELINE/opportunites -->
+# Inventaire de modélisation — CRM / PIPELINE / opportunites
+_Pass 1 (rapide) · planning · à détailler via /ba-modeling-detail · régénéré à chaque passage_
+
+## Cas d'usage candidats
+
+| Item | Type | Intention (1 ligne) | Acteur principal | Complexité |
+|------|------|---------------------|------------------|------------|
+| UC-CRM-PIPELINE-OPPORTUNITES-001 | UC | Créer une opportunité depuis un prospect | BA-001-AC-001 (Commercial) | simple |
+| UC-CRM-PIPELINE-OPPORTUNITES-002 | UC | Faire valider une remise > 20 % par le manager | BA-001-AC-002 (Manager) | complex |
+
+## Règles métier candidates
+
+| Item | Type | Intention (1 ligne) | Portée | Complexité |
+|------|------|---------------------|--------|------------|
+| BR-001 | BR | Remise > 20 % exige l'aval manager | CRM / PIPELINE | moderate |
+| BR-002 | BR | L'email d'un contact est unique par compte | CRM / PIPELINE | simple |
+```
+
+Rules for the file:
+
+- One `## Cas d'usage candidats` table and one `## Règles métier candidates`
+  table. An empty scope is fine — keep the heading and write
+  `_(aucun cas d'usage modélisable pour l'instant)_` under it.
+- **Item** is the code (see formats below). **Type** is literally `UC` or `BR`.
+  **Intention** is ONE short line (`verb + object`, ~3-7 words) matching the
+  actor's mental model. **Complexité** is exactly one of `simple | moderate |
+  complex`.
+- For UCs, name the **Acteur principal** by its verbatim `BA-…-AC-…` code +
+  label. For rules, give the **Portée** as the node path the rule attaches to
+  (`CRM / PIPELINE` or `… / opportunites`).
+- The anchor first line is `<!-- ba:inventory scope=<path> -->` — a planning
+  marker, deliberately NOT one of the authoritative `kind=` values, so audits and
+  `create-prd` skip it.
+
+## Code formats (match the authoritative docs verbatim)
+
+These are the **native** formats the detail pass and the audits expect — copy
+them, never compose or translate (see `_workflow/code-discipline.md`):
+
+- **Use case** — `UC-{APP}-{MOD}-{SEC}-NNN`, where `{APP}`/`{MOD}` are the
+  UPPERCASE app/module folder codes and `{SEC}` is the section folder code
+  UPPERCASED with `-` → `_` (folder `exchange-history` → `EXCHANGE_HISTORY`,
+  `opportunites` → `OPPORTUNITES`). `NNN` is a zero-padded 3-digit counter
+  **scoped to the section**, restarting at `001` per section.
+- **Business rule** — `BR-{NNN}`, a 3-digit counter **scoped to the doc** (the
+  rule's deepest declared scope). The number, never the title, is the identity.
+
+Before numbering, **Grep** the scope's existing `use-case.md` / `règles-métier.md`
+headings (and any prior `_inventory.md`) for the highest taken number and
+increment. Preserve any code that already exists — this is an additive merge, so
+a re-run keeps prior codes stable and only appends new candidates.
+
+> Note: this differs from the legacy Studio scheme that namespaced rule codes per
+> section (`BR-<APP>-<MOD>-<SEC>-NNN`). Native BA uses the simpler `BR-{NNN}`
+> scoped to the owning doc — match the authoritative `règles-métier.md`.
+
+## Complexity taxonomy (critical — drives Pass 2 effort routing)
+
+- **simple** → CRUD-shaped UCs, trivial validations (unique, required, format),
+  one actor, one entity, no cross-entity impact. Pass 2 can write these directly
+  with little elaboration.
+- **moderate** → multi-step flows (≥3 steps), 2+ actors, single aggregate,
+  conditional branches. Pass 2 elaborates the full flow / examples.
+- **complex** → multi-entity impact, state machines, approvals / workflows,
+  temporal constraints, externally-triggered side effects, audit trails. Pass 2
+  spends the most effort here.
+
+Be **honest** with the flags. A mis-flagged `simple` that is really `complex`
+yields a shallow detail pass; a mis-flagged `complex` wastes effort on a trivial
+flow. When in doubt, flag `moderate`.
+
+## Hard rules
+
+- Read the tree first; **Write exactly one file** (`_inventory.md` for the
+  scope). No conversational back-and-forth is required for Pass 1 — it is a fast
+  enumeration. (You may ask one closed scope-clarifying question if the user's
+  scope is ambiguous, but the default is: infer the scope and produce the file.)
+- Include **all** relevant UCs + rules for the scope. An empty scope is valid —
+  write the headings with an `_(aucun …)_` note.
+- Every UC must reference an **existing** actor from `<APP>/acteur.md`. Never
+  invent an actor — that belongs to `/ba-create-actors`.
+- **No flows, no preconditions, no examples, no expressions, no diagrams.** The
+  inventory is SHALLOW by design — Pass 2 fills those in for the flagged items.
+- Never invent a UC, rule, actor, section, module or app code. Copy actor codes
+  from `acteur.md`, node codes from the folder names; if something is missing,
+  defer to its owner phase (`/ba-create-menu`, `/ba-create-actors`).
+- Never switch languages mid-scope — write the file in the user's language; this
+  SKILL.md stays English.
+
+## After writing → hand off to the detail pass
+
+Acknowledge in one line ("Inventaire `opportunites` — 6 cas d'usage, 4 règles.")
+and tell the user the next step: **`/ba-modeling-detail`** expands each
+**moderate** and **complex** item into the real authoritative docs
+(`use-case.md` / `règles-métier.md`), one item per call; **simple** items can be
+written directly via `/ba-create-use-case` / `/ba-create-business-rules`
+without further elaboration. The `_inventory.md` is the checklist driving that
+pass; it is regenerated, not edited by hand.
+
+## Talking to the user
+
+Speak like a business analyst, not a tool. Don't surface skill names, file paths,
+anchors, or the `.smartstack/ba/` layout to the end user — talk about "the menu",
+"the actors", "the use cases and rules for this scope". The `/ba-*` references in
+this file are for your own routing.

package/templates/skills/business-analyse/reconcile-menu/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: ba-reconcile-menu
+description: >
+  Reconciles the `.smartstack/ba/` menu tree (sections/modules currently in
+  `index.md`) against the codes embedded in downstream documents (`use-case.md`,
+  `screen.md`, `règles-métier.md`, `rbac.md`). Detects RENAMES (heuristic) and
+  DELETIONS, asks the user to validate the diff, then rewrites the downstream
+  docs (drops stranded UC/SCR/BR/RBAC blocks, scrubs body references, renames
+  codes in place). Idempotent. Run AUTOMATICALLY as Phase 0.5 of `/ba-loop`
+  whenever the menu was modified after content was created — never skip a
+  modified menu, always audit and correct.
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
+argument-hint: '[--dry-run] [--app APPCODE]'
+---
+
+# ba-reconcile-menu — Menu reconciliation
+
+You are the **menu reconciler**. Your job: when the user has modified the
+menu tree (`/ba-create-menu`) after downstream content was generated,
+detect what changed (rename or delete of a section/module) and either
+**migrate** the existing UC/SCR/BR/RBAC codes to the new code or **clean
+up** the stranded blocks.
+
+You **never invent content** — you delete stale references and rename codes
+that the heuristic (Levenshtein + UC overlap) confidently matches. When in
+doubt, you **defer to the user** via `AskUserQuestion` before applying.
+
+## Why this skill exists
+
+`/ba-loop` (and the per-phase `/ba-create-*` skills) operate in "enrich" mode
+— they **add** items but **never remove**. If a section disappears from the
+menu, its UCs / screens / rules still exist in the downstream files and
+become orphans. The audits don't detect this by default (the SEC-007 and
+UC-019 rules were added to catch it, but those audits **report** the problem;
+this skill **fixes** it).
+
+The rule the orchestrator follows:
+
+> **En cas de modification du menu lors d'un rerun, tu ne peux pas skipper :
+> tu dois auditer si ce qui a été fait est correct et corriger si ce ne
+> l'est pas.**
+
+## Inputs
+
+- The `.smartstack/ba/` tree must exist (otherwise the menu hasn't even been
+  created — defer to `/ba-create-menu`).
+- Optional `--app APPCODE`: scope to one application (default: all).
+- Optional `--dry-run`: report the plan without writing.
+
+## Workflow
+
+### Step 1 — Dry-run scan
+
+Invoke the CLI in dry-run mode to discover what changed:
+
+```bash
+npx tsx skills/business-analyse/reconcile-menu/cli/reconcile-menu/index.ts \
+  --spec '{"baRoot": ".smartstack/ba", "dryRun": true}'
+```
+
+The CLI returns a JSON envelope describing:
+- `renames[]` — sections/modules whose code changed in the tree but whose
+  downstream codes still use the old name. Each rename carries a confidence
+  score (0..1) and a reason (`code-similar`, `uc-overlap`, or both).
+- `deletions[]` — sections/modules referenced by codes but absent from the
+  tree, with no rename match.
+- `staleRefs[]` — every code that points to a ghost section, useful for
+  display.
+
+If **both arrays are empty** → the tree is consistent. Report a one-liner to
+the user (`"Menu cohérent — aucune réconciliation nécessaire."`) and stop.
+
+### Step 2 — Show the diff + validate
+
+Present the diff to the user as a single `AskUserQuestion` (closed choices):
+
+```
+J'ai détecté les écarts suivants entre le menu actuel et les documents
+downstream :
+
+— RENAMES (sections renommées) —
+  - CRM/PIPELINE/OPPORTUNITES → CRM/PIPELINE/PROSPECTS (confiance 92%, code-similar+uc-overlap)
+    Tous les UC/SCR/BR/RBAC seront réécrits sur le nouveau code.
+
+— SUPPRESSIONS (sections supprimées) —
+  - CRM/PIPELINE/LEGACY (3 codes orphelins, raison : no-rename-candidate)
+    Les blocs UC/SCR seront supprimés et les références body nettoyées.
+
+Que veux-tu faire ?
+```
+
+Options:
+- **Appliquer la réconciliation** (recommandé) — applies all changes.
+- **Voir le détail** — pre-prints each `staleRefs[].file:line` then re-asks.
+- **Skipper cette réconciliation** — emits a verdict file with severity
+  `warn` and aborts (downstream audits will then block).
+
+### Step 3 — Apply
+
+If validated, invoke the CLI without `--dry-run`:
+
+```bash
+npx tsx skills/business-analyse/reconcile-menu/cli/reconcile-menu/index.ts \
+  --spec '{"baRoot": ".smartstack/ba"}'
+```
+
+The CLI:
+1. For each RENAME: substitutes every `(KIND)-APP-MOD-OLD-NNN` →
+   `(KIND)-APP-MOD-NEW-NNN` in every downstream file.
+2. For each DELETION: drops every heading block whose code matches the
+   deleted (APP,MOD,SEC) triplet, scrubs body references (comma-separated
+   lists collapse correctly; empty `Règles liées` lines become `—`).
+3. Removes any orphan section directory still on disk.
+4. Writes `.smartstack/ba/_audit/reconcile.md` (the verdict).
+
+### Step 4 — Report
+
+Surface a 3–6 line business summary:
+
+```
+Réconciliation appliquée :
+- 1 section renommée (PROSPECTS), 2 codes migrés
+- 1 section supprimée (LEGACY), 3 blocs nettoyés + 1 dossier retiré
+- 5 fichiers modifiés
+
+→ Relance /ba-loop pour ré-enrichir les sections renommées.
+```
+
+## Decision table
+
+| Situation | Action |
+|-----------|--------|
+| Tree is consistent (no renames, no deletions) | One-liner OK, no Write, no user prompt |
+| Renames only, all confidence ≥ 0.8 | Show diff + validate, then apply |
+| Renames with confidence < 0.8 | Highlight low-confidence renames in the AskUserQuestion description; let user opt out per rename via free-text "Other" |
+| Deletions only | Show diff + validate (deletions are destructive — git is the safety net) |
+| Mix of renames + deletions | Show both blocks in the same AskUserQuestion |
+| User picks "Skipper" | Write verdict with severity `warn`, abort |
+| CLI returns `success: false` | Surface the `errors[]` to the user, halt |
+
+## Guard rails
+
+- **Never apply without showing the diff** — even on a single rename. The
+  user must see what is about to change.
+- **Never edit the menu tree itself** — that's `/ba-create-menu`'s job. This
+  skill ONLY touches downstream docs.
+- **Never invent codes** — the rename/delete decisions come from the
+  deterministic CLI; you do not extrapolate.
+- **Idempotent** — running twice in a row is a no-op (the second pass
+  detects no remaining ghosts).
+- **`git` is the safety net** — deletions are physical (no archive folder).
+  The user can `git diff` / `git checkout` to recover.
+
+## How the heuristic works (for transparency)
+
+The CLI matches each "ghost" (section referenced by codes but absent from
+the tree) against the "arrivals" (sections present in the tree without any
+code) using two signals:
+
+- **Code similarity**: Levenshtein distance normalised over the longer
+  string length. < 0.3 → strong match (`OPPORTUNITES` ↔ `OPPORTUNITY` =
+  0.08).
+- **UC overlap**: Jaccard similarity of the UC heading titles between
+  ghost and arrival (after lowercasing + accent stripping). ≥ 0.5 → strong
+  match.
+
+A rename is "clear" when **exactly one arrival** scores high enough AND
+**beats the runner-up by ≥ 0.3 confidence**. Otherwise → DELETE (the user
+can still rename manually before re-running).
+
+## Used by the loop orchestrator
+
+`/ba-loop` invokes this skill as **Step 0.5 — Menu reconciliation preflight**
+(between Step 0 read-state and Step 1 actors). When `renames + deletions = 0`
+the loop continues silently; otherwise the loop **pauses**, asks the user
+via this skill, and only resumes after reconciliation is applied or
+explicitly skipped.
+
+This is the answer to "**you can't skip a modified menu — audit and
+correct**".