@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/ba-develop-plan/cli/preflight-develop-plan/validate.ts

@@ -0,0 +1,261 @@
+/**
+ * validate.ts — Validates the development plan and checks per-module readiness.
+ *
+ * Reads dev-plan.json (produced by /ba-create-plan-development) and verifies that
+ * each module has the required PRD files and a passing audit verdict.
+ */
+import path from 'node:path';
+import {
+  fileExists,
+  directoryExists,
+  readJson,
+  readText,
+} from '../../../../lib/fs.js';
+import { PreflightInputSchema } from './types.js';
+import type {
+  PreflightInput,
+  DevelopmentPlan,
+  ReadinessInfo,
+  ModulePreflight,
+  WavePreflight,
+  PreflightReport,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Readiness verdict parsing (same regex as create-plan-development/parse.ts)
+// ---------------------------------------------------------------------------
+
+const VERDICT_RE =
+  /Verdict\s*:\s*(GO|NO-GO)(?:.*?score\s+(\d+))?(?:.*?(\d+)\s+err)?(?:.*?(\d+)\s+warn)?/;
+
+async function parseReadiness(
+  auditPath: string,
+): Promise<ReadinessInfo> {
+  const exists = await fileExists(auditPath);
+  if (!exists) return { verdict: 'UNKNOWN' };
+
+  const content = await readText(auditPath);
+  const match = VERDICT_RE.exec(content);
+  if (!match) return { verdict: 'UNKNOWN' };
+
+  return {
+    verdict: match[1] as 'GO' | 'NO-GO',
+    score: match[2] ? Number(match[2]) : undefined,
+    errCount: match[3] ? Number(match[3]) : undefined,
+    warnCount: match[4] ? Number(match[4]) : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export interface ValidateResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  spec?: PreflightInput;
+  plan?: DevelopmentPlan;
+}
+
+/**
+ * Stage 1: Zod validation + plan file existence.
+ */
+export async function validateInput(raw: unknown): Promise<ValidateResult> {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const parsed = PreflightInputSchema.safeParse(raw);
+  if (!parsed.success) {
+    const zodErrors = parsed.error.issues.map(
+      (i) => `${i.path.join('.')}: ${i.message}`,
+    );
+    return { valid: false, errors: zodErrors, warnings };
+  }
+
+  const spec = parsed.data;
+
+  // Check baRoot exists
+  if (!(await directoryExists(spec.baRoot))) {
+    errors.push(`BA root not found: ${spec.baRoot}`);
+    return { valid: false, errors, warnings };
+  }
+
+  // Check dev-plan.json exists
+  const planPath = path.join(spec.baRoot, '_plan', 'dev-plan.json');
+  if (!(await fileExists(planPath))) {
+    errors.push(
+      `Development plan not found: ${planPath}. Run /ba-create-plan-development first.`,
+    );
+    return { valid: false, errors, warnings };
+  }
+
+  // Read and parse the plan
+  let plan: DevelopmentPlan;
+  try {
+    plan = await readJson<DevelopmentPlan>(planPath);
+  } catch (err) {
+    errors.push(
+      `Failed to parse dev-plan.json: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return { valid: false, errors, warnings };
+  }
+
+  // Basic plan validation
+  if (!plan.waves || plan.waves.length === 0) {
+    errors.push('Development plan has no waves');
+    return { valid: false, errors, warnings };
+  }
+
+  // Check projectPath exists
+  if (!(await directoryExists(spec.projectPath))) {
+    errors.push(`Project path not found: ${spec.projectPath}`);
+    return { valid: false, errors, warnings };
+  }
+
+  // Warn about cycles
+  if (plan.cycles && plan.cycles.length > 0) {
+    warnings.push(
+      `Plan contains ${plan.cycles.length} circular dependency group(s) — co-develop those modules`,
+    );
+  }
+
+  return { valid: true, errors, warnings, spec, plan };
+}
+
+/**
+ * Stage 2: Per-module readiness check.
+ * Returns the full preflight report.
+ */
+export async function checkReadiness(
+  spec: PreflightInput,
+  plan: DevelopmentPlan,
+): Promise<PreflightReport> {
+  const wavesToCheck = plan.waves.filter((w) => w.level > 0);
+  const wavePreflights: WavePreflight[] = [];
+  let readyCount = 0;
+  let blockedCount = 0;
+  let externalCount = 0;
+
+  // Wave 0: externals (just count them)
+  const wave0 = plan.waves.find((w) => w.level === 0);
+  if (wave0) {
+    externalCount = wave0.modules.length;
+  }
+
+  for (const wave of wavesToCheck) {
+    // Filter waves if the user specified specific ones
+    if (spec.waves && spec.waves.length > 0 && !spec.waves.includes(wave.level)) {
+      continue;
+    }
+
+    const modulePreflights: ModulePreflight[] = [];
+    const waveBlockers: string[] = [];
+
+    for (const mod of wave.modules) {
+      const preflight = await checkModule(spec.baRoot, mod.appCode, mod.moduleCode, wave.level);
+      modulePreflights.push(preflight);
+
+      if (preflight.status === 'ready') {
+        readyCount++;
+      } else {
+        blockedCount++;
+        waveBlockers.push(`${mod.key}: ${preflight.blockers.join('; ')}`);
+      }
+    }
+
+    wavePreflights.push({
+      level: wave.level,
+      status: waveBlockers.length === 0 ? 'ready' : 'blocked',
+      modules: modulePreflights,
+      blockers: waveBlockers,
+    });
+  }
+
+  // Determine which waves can proceed
+  let firstReadyWave: number | null = null;
+  let lastReadyWave: number | null = null;
+
+  for (const wp of wavePreflights) {
+    if (wp.status === 'ready') {
+      if (firstReadyWave === null) firstReadyWave = wp.level;
+      lastReadyWave = wp.level;
+    } else {
+      // A blocked wave stops the chain
+      break;
+    }
+  }
+
+  return {
+    planDate: plan.generatedAt,
+    apps: plan.apps,
+    projectPath: spec.projectPath,
+    totalModules: readyCount + blockedCount,
+    readyModules: readyCount,
+    blockedModules: blockedCount,
+    externalDeps: externalCount,
+    hasCycles: (plan.cycles?.length ?? 0) > 0,
+    waves: wavePreflights,
+    canProceed: firstReadyWave !== null,
+    firstReadyWave,
+    lastReadyWave,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-module check
+// ---------------------------------------------------------------------------
+
+async function checkModule(
+  baRoot: string,
+  appCode: string,
+  moduleCode: string,
+  waveLevel: number,
+): Promise<ModulePreflight> {
+  const key = `${appCode}/${moduleCode}`;
+  const moduleDir = path.join(baRoot, appCode, moduleCode);
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+
+  // Check PRD files
+  const prdFiles = {
+    prd: await fileExists(path.join(moduleDir, 'prd.md')),
+    entities: await fileExists(path.join(moduleDir, 'prd.entities.md')),
+    api: await fileExists(path.join(moduleDir, 'prd.api.md')),
+    frontend: await fileExists(path.join(moduleDir, 'prd.frontend.md')),
+    pagespecs: await directoryExists(path.join(moduleDir, 'pagespecs')),
+  };
+
+  if (!prdFiles.prd) blockers.push('prd.md missing — run /ba-create-prd');
+  if (!prdFiles.entities) blockers.push('prd.entities.md missing');
+  if (!prdFiles.api) blockers.push('prd.api.md missing');
+  if (!prdFiles.frontend) blockers.push('prd.frontend.md missing');
+  if (!prdFiles.pagespecs) warnings.push('pagespecs/ directory missing — frontend phase may have issues');
+
+  // Check audit readiness
+  const auditPath = path.join(moduleDir, '_audit', 'prd.md');
+  const readiness = await parseReadiness(auditPath);
+
+  if (readiness.verdict === 'UNKNOWN') {
+    blockers.push('_audit/prd.md missing — run /ba-audit-prd');
+  } else if (readiness.verdict === 'NO-GO') {
+    blockers.push(
+      `Audit verdict: NO-GO${readiness.score != null ? ` (score ${readiness.score}/100)` : ''}${readiness.errCount != null ? ` — ${readiness.errCount} err` : ''}`,
+    );
+  } else if (readiness.verdict === 'GO' && readiness.score != null && readiness.score < 80) {
+    blockers.push(`Audit score ${readiness.score}/100 < 80 — not dev-ready`);
+  }
+
+  return {
+    appCode,
+    moduleCode,
+    key,
+    wave: waveLevel,
+    status: blockers.length === 0 ? 'ready' : 'not-ready',
+    moduleDir,
+    readiness,
+    prdFiles,
+    blockers,
+    warnings,
+  };
+}

package/templates/skills/business-analyse/_workflow/README.md

@@ -0,0 +1,34 @@
+# _workflow — shared references for the BA skills (repo-only)
+
+This folder holds the **shared conventions** the `business-analyse/` skills are
+written against. It is NOT deployed: the installer skips `_workflow/` (and any
+`CLAUDE.md` index) because Claude Code only registers skills that are direct
+children of the skills root. Each `ba-*` skill **inlines** what it needs from
+these files, so it is self-contained at runtime — these docs are the source of
+truth used when authoring/maintaining the skills.
+
+## The model in one line
+
+There is no Studio, no database, no `[ACTION]`/`[QUESTION]` blocks, no injected
+`--- CURRENT X ---` state. **The `.smartstack/ba/` markdown tree IS the state.**
+Skills read it (Read/Glob/Grep), ask closed choices with **AskUserQuestion**, and
+persist by **writing `.md` files** with the Write tool.
+
+## Files here
+
+| File | Role |
+|------|------|
+| `ba-files.md` | The file model: `.smartstack/ba/` layout, the Application→Module→Section→Resource tree, the six docs per node, the authority matrix (one authoritative level per concept, rollups are one-line pointers), `<!-- ba:* -->` anchors, read-as-state + Write-overwrites semantics. |
+| `doc-templates.md` | Canonical markdown skeletons for every doc (`index`, `acteur`, `use-case`, `règles-métier`, `rbac`, `entité`, `screen`) + the rollup variant + the `_audit/<dimension>.md` verdict shape. The single parse target shared by authors, audits and `create-prd`. |
+| `communication.md` | Cross-phase communication rules + ACK shape + safety (use your tools; talk like a business analyst, not a tool). |
+| `code-discipline.md` | Verbatim copy rule + the identifier universe + the 7 historical code drifts. Source of truth = the files (Grep), not memory. |
+| `context-documents.md` | How to use user-provided reference docs (read them with the Read tool). |
+| `completeAuto-discipline.md` | Anti-hallucination guard for "complete (auto)" coverage runs — every proposal needs a verbatim trace in the tree. |
+
+## Phase order (fixed)
+
+`menu → actors → use cases → rules → RBAC → data model → screens`, then
+`/ba-create-prd` → `/ba-audit-pre-dev` (GO) → `/ba-develop`.
+Each per-dimension `/ba-audit-*` reads the tree and writes a `_audit/<dim>.md`
+verdict; the definer does a light self-check before writing and hands off to the
+next phase.

package/templates/skills/business-analyse/_workflow/ba-files.md

@@ -0,0 +1,174 @@
+---
+name: ba-files
+description: >
+  The file-based persistence model for the BA workflow in native Claude Code.
+  The `.smartstack/ba/` markdown tree IS the database — there is no Studio, no
+  SQLite, no `[ACTION]` blocks. Read the tree as state, write `.md` with the
+  Write tool. Replaces the Studio-era `output-schema.md`.
+phase: '*'
+kind: companion
+mode_pinned: true
+section_label: '_WORKFLOW — FILE MODEL (.smartstack/ba)'
+---
+
+# BA file model — the markdown tree is the database
+
+In native Claude Code there is **no Studio, no SQLite, no backend route, no
+`[ACTION]`/`[QUESTION]` block, no injected `--- CURRENT X ---` state**. Your
+state is the `.smartstack/ba/` directory in the user's project. You:
+
+1. **Read** the tree (Glob + Read) at the start of every task to know what exists.
+2. **Propose** in prose; ask closed choices with the **AskUserQuestion** tool.
+3. **Write** `.md` files with the **Write** tool once the user validates.
+
+There is no watchdog and no input lock. A skill that "persists" simply writes a
+file. A skill that "reads current state" simply reads files.
+
+## Output root & layout
+
+Everything lives under **`.smartstack/ba/`** in the current project
+(`.smartstack/` is already SmartStack's project-local config dir). Each node of
+the Application → Module → Section → Resource hierarchy is a **folder named by
+its code**, and every node folder carries `index.md` + the six concept docs:
+
+```
+.smartstack/ba/
+├─ index.md                      ← PROJECT metadata (name, context, global out-of-scope, app list)
+└─ CRM/                          ← Application  (code UPPERCASE)
+   ├─ index.md
+   ├─ acteur.md
+   ├─ entité.md
+   ├─ use-case.md
+   ├─ règles-métier.md
+   ├─ screen.md
+   ├─ rbac.md
+   ├─ _audit/                    ← audit verdicts for this node (menu.md, actors.md, …)
+   └─ PIPELINE/                  ← Module  (code UPPERCASE)
+      ├─ index.md … (same 6 docs + _audit/)
+      ├─ prd.md                  ← PRD synthesis (module level only — see create-prd)
+      ├─ prd.entities.md / prd.api.md / prd.frontend.md
+      ├─ pagespecs/<Entity>.<view>.md
+      ├─ claude.md
+      ├─ audit.json              ← dev-readiness gate (generated, see audit-prd)
+      └─ opportunites/           ← Section  (folder = code, lower-kebab ASCII)
+         ├─ index.md … (same 6 docs)
+         └─ devis/               ← Resource (folder = code, lower-kebab ASCII)
+            └─ index.md … (same 6 docs)
+```
+
+The **folder structure encodes the menu hierarchy**; each folder is named by its
+**node code** and each `index.md` holds the node metadata (incl. the accented
+label). Codes are ASCII (UPPERCASE apps/modules, lower-kebab sections/resources),
+so `Opportunités` (label) lives in a folder named `opportunites` (code).
+Generated doc CONTENT is in the user's language; this SKILL.md and all skill
+files stay in English.
+
+> The six **doc filenames** are intentionally French and accented (`acteur.md`,
+> `entité.md`, `use-case.md`, `règles-métier.md`, `screen.md`) — keep them
+> verbatim. Only the **folder names** are ASCII codes.
+
+## The six docs + index — what each holds
+
+| File | Owner skill | Holds |
+|------|-------------|-------|
+| `index.md` | create-menu | node code, label, context, out_of_scope, list of children |
+| `acteur.md` | create-actors | actors (`BA-{NNN}-AC-{NNN}`): label, type, description, scope |
+| `use-case.md` | create-use-case | Cockburn UCs (`UC-{APP}-{MOD}-{SEC}-NNN`) |
+| `règles-métier.md` | create-business-rules | rules (`BR-…`): condition, expression, valid/invalid examples, linked UCs |
+| `rbac.md` | create-rbac | permission matrix: actor × action × scope |
+| `entité.md` | create-data-model | MCD entities (`ENT-…`): attributes, relationships, indexes |
+| `screen.md` | create-screen | screen specs (`SCR-…`): SmartComponent type, entity, config |
+
+BA docs carry **no diagrams** — visual ERD / sequence rendering is a Studio
+concern, not part of the file-based BA output.
+
+## Authority matrix — single source of truth, no drift
+
+The six docs **exist at every level** (uniform, predictable structure). To avoid
+divergent duplication, **exactly one level is AUTHORITATIVE per concept**; the
+other levels carry an **auto-generated rollup** — a short aggregated/filtered
+view that links to the authoritative children and never contains hand-authored
+prose.
+
+| Doc | App | Module | Section | Resource | Authoritative level |
+|-----|-----|--------|---------|----------|---------------------|
+| `index.md` | author | author | author | author | every node (intrinsic metadata) |
+| `acteur.md` | **author** | rollup | rollup | rollup | App (actors are app/project-scoped) |
+| `rbac.md` | rollup | **author** | author | author | Module (perms attach to actor × target) |
+| `use-case.md` | rollup | rollup | **author** | refine | Section (`UC-{APP}-{MOD}-{SEC}-NNN`) |
+| `règles-métier.md` | author | author | author | author | the rule's deepest declared scope |
+| `entité.md` | rollup | **author** | rollup | rollup | Module (MCD per module) |
+| `screen.md` | rollup | rollup | **author** | author | Section / Resource (screen binds there) |
+
+A rollup file starts with the marker `<!-- ba:rollup auto -->` immediately after
+its anchor comment. **Never hand-edit a rollup** — it is regenerated from its
+authoritative children. An authoritative file never carries the rollup marker.
+
+## Anchor markers — how files are parsed back into state
+
+Every doc starts with an HTML-comment anchor so a later turn (or an audit) can
+reconstruct state by reading files:
+
+```
+<!-- ba:node kind=acteur level=application code=CRM -->
+```
+
+- `kind` ∈ `node | acteur | use-case | rules | rbac | entité | screen | prd | audit`
+- `level` ∈ `project | application | module | section | resource`
+- `code` = the node code this doc is scoped to
+- `depends` (optional, module-level `index.md` only) = comma-separated `APP/MODULE`
+  keys listing cross-module BA dependencies. Written by `/ba-create-ba-order`
+  (Phase 1.5). Example: `depends=ERP/REFERENCES,ERP/CUSTOMERS`.
+  Absent means "no dependencies declared yet" (not "none").
+
+Individual items inside a doc use a `### {CODE} — {label}` heading so codes are
+greppable. The code **prefixes are the functional identifiers** and are found by
+Grep on the tree — not from any injected block:
+
+| Identifier | Format | Found in |
+|------------|--------|----------|
+| application / module code | UPPERCASE | folder name + `index.md` anchor |
+| section / resource code | lower-kebab | folder name + `index.md` anchor |
+| actor code | `BA-{NNN}-AC-{NNN}` | `acteur.md` headings |
+| use-case code | `UC-{APP}-{MOD}-{SEC}-NNN` | `use-case.md` headings |
+| rule code | `BR-{NNN}` | `règles-métier.md` headings |
+| entity code | `ENT-{NNN}` | `entité.md` headings |
+| screen code | `SCR-{APP}-…-NNN` | `screen.md` headings |
+
+## Reading the tree as state (do this first, every task)
+
+1. `Glob .smartstack/ba/**/index.md` → the full node tree (folders = hierarchy).
+2. Read the `index.md` of the node(s) in scope for metadata (label, context, out_of_scope).
+3. For the concept you work on, Read the authoritative `<concept>.md` of the
+   relevant node(s). To reference a code, Grep it across the tree — if it is not
+   found, it does not exist (do not invent it; offer to create it).
+
+If `.smartstack/ba/` does not exist, you are at project start: create it and
+`index.md` as part of the first `create-menu` turn.
+
+## Writing (Write tool — overwrite semantics)
+
+- A persist = **Write the full authoritative doc** for the node. The Write
+  **overwrites** the file, so any item you omit is removed — re-list every item
+  that must survive (this replaces the old "orphan cleanup" discipline).
+- The authoritative doc holds the real content. At every OTHER level the doc
+  still exists (uniform structure) but as a **rollup**. The **minimal, preferred
+  form of a rollup is a one-line pointer** to the authoritative doc
+  (`> Voir [chemin](...)`) — keep rollups pointer-thin so they cannot drift. An
+  aggregated list of child codes is optional, never required. Only refresh a
+  rollup when you are already touching that subtree; do not fan out across the
+  whole tree on every write.
+- `create-menu` scaffolds each new node folder with `index.md` + six
+  placeholder docs (anchor + `_À définir via /<skill>_`), so the structure is
+  uniform from creation. Phase skills replace placeholders with real content at
+  the authoritative level.
+- Confirm destructive edits (removing a node, an actor, a permission) with
+  AskUserQuestion before writing.
+
+## Code discipline (carried over — still load-bearing)
+
+The verbatim-copy rule survives, with the source of truth now being the `.md`
+tree instead of injected blocks. Never translate, compose, or invent a code:
+copy it verbatim from the file where it is authored. See `code-discipline.md`
+for the seven historical drifts (label→SCREAMING_SNAKE, FR↔EN, dot-composition,
+invented codes, …) — they all still apply.

package/templates/skills/business-analyse/_workflow/code-discipline.md

@@ -0,0 +1,104 @@
+---
+name: code-discipline
+description: Verbatim copy rule + identifier discipline — anti-drift companion. Source of truth is the `.smartstack/ba/` markdown tree (read with Grep), not injected blocks.
+phase: '*'
+kind: companion
+mode_pinned: true
+section_label: '_WORKFLOW — CODE DISCIPLINE (verbatim copy rule)'
+---
+
+# Code discipline (verbatim copy rule)
+
+Read this before writing any doc that references a code.
+
+## ⚠️ Source of truth: the `.md` tree, NOT your memory (ALL PHASES)
+
+State lives in `.smartstack/ba/` (see `ba-files.md`). The files contain the
+**exact list of items that exist right now** — that is the only source of truth.
+Your memory of the conversation can be stale (an item may have been removed by a
+later write, or never written).
+
+**Before referring to an item (BR-XYZ, UC-XYZ, BA-NNN-AC-NNN, ENT-NNN, …) as
+"existing" / "already defined"**, Grep it across the tree. If it is absent:
+
+✅ **Correct**:
+> Vous mentionnez BR-CRM-002. Je ne le trouve pas dans les règles enregistrées —
+> il n'a probablement jamais été défini. Voulez-vous que je le crée ?
+
+❌ **Anti-pattern**:
+> Les règles BR-002, BR-005 sont toujours en attente.
+> *(alors qu'aucune n'apparaît dans `règles-métier.md`)*
+
+### Per-turn check
+
+1. `Glob`/`Read`/`Grep` the relevant docs in `.smartstack/ba/`.
+2. Note the codes actually present.
+3. Before mentioning a code in prose or a coverage recap:
+   - Present in a file → OK, speak in the present tense.
+   - Absent → either create it (write it into the authoritative doc) or flag the
+     gap. NEVER claim it exists when no file contains it.
+
+## Verbatim copy rule (ABSOLUTE, ALL PHASES)
+
+**Every identifier you write into a doc MUST be copied verbatim from the file
+where it is authored.** Never translate, compose, transform, infer or invent a
+code. Cross-references (a screen linking a UC, a rule linking a UC) break
+silently if the code drifts.
+
+| Category | Source of truth | Example of drift |
+|----------|-----------------|------------------|
+| **Identifier values** (codes) | the authoring `.md` file (Grep it) | `GESTIONNAIRE_STOCK` instead of `BA-002-AC-007` (label → SCREAMING_SNAKE); `MOVEMENTS` instead of `MOUVEMENTS` (FR→EN); `STOCK.MOUVEMENTS` instead of `STOCK` + `MOUVEMENTS`; `UC-STOCK-CATALOGUE-PARTS-003` invented |
+| **Field/section names** in a doc | the relevant skill's doc template | renaming a template heading so a later parse/audit misses it |
+
+If you can't find the exact string in a file, you're inventing it. Stop and
+Grep.
+
+## The identifier universe
+
+| Identifier | Authored in | Format |
+|------------|-------------|--------|
+| `applicationCode` / `moduleCode` | folder name + `index.md` anchor | UPPERCASE (e.g. `STOCK`, `MOUVEMENTS` — never `MOVEMENTS`) |
+| `sectionCode` / `resourceCode` | folder name + `index.md` anchor | lower-kebab (e.g. `exchange-history`) |
+| `actorCode` | `acteur.md` headings | `BA-{NNN}-AC-{NNN}` — sequence-based, NOT label-derived |
+| `useCaseCode` | `use-case.md` headings | `UC-{APP}-{MOD}-{SEC}-NNN` |
+| `ruleCode` | `règles-métier.md` headings | `BR-{NNN}` |
+| `entityCode` | `entité.md` headings | `ENT-{NNN}` |
+| `screenCode` | `screen.md` headings | `SCR-{APP}-…-NNN` |
+
+To assign the next code in a sequence, Grep the existing codes of that family in
+scope and increment — never reuse a removed code in the same scope.
+
+## The 7 drifts that cost real data
+
+Each has happened. Recognise them and STOP before writing.
+
+1. **SCREAMING_SNAKE from the label** — `GESTIONNAIRE_STOCK` from "Gestionnaire
+   de stock" when the real code is `BA-002-AC-007`. Label = UI text; code = key.
+2. **French↔English translation** — `MOVEMENTS` when the module code is
+   `MOUVEMENTS`. Never translate — the code is whatever was validated in phase 1.
+3. **Dot-notation composition** — `STOCK.MOUVEMENTS` when app and module are
+   separate codes (`STOCK`, `MOUVEMENTS`).
+4. **SCREAMING_SNAKE the section label** — `EXCHANGE_HISTORY` when the section
+   code is `exchange-history`. Section codes are lower-kebab.
+5. **Invented UC codes** — `UC-STOCK-CATALOGUE-PARTS-003` for a section never
+   detailed. A UC code MUST be visible in a `use-case.md` to be referenced.
+6. **Invented item names** — referencing an entity/rule/screen that no file
+   authors. Grep first.
+7. **"Prettier" actor codes** — `STOCK_MANAGER`, `GestionnaireStock`. Codes are
+   ugly by design (traceability > aesthetics). Copy them as-is.
+
+## Verify references before you write
+
+Before writing a doc that references codes from other docs (e.g. a `screen.md`
+referencing a UC and an entity), restate the codes you are about to use and
+confirm each one appears verbatim in its authoring file:
+
+```
+Scope        : STOCK / CATALOGUE / parts
+Actors       : BA-002-AC-007 (Gestionnaire de stock)   ← acteur.md
+Linked UCs   : UC-STOCK-CATALOGUE-PARTS-001..005        ← use-case.md
+Linked rules : BR-003, BR-007                            ← règles-métier.md
+```
+
+If a code is not found in its authoring file, the referenced item does not
+exist — defer to the phase that creates it rather than fabricating the code.

package/templates/skills/business-analyse/_workflow/communication.md

@@ -0,0 +1,63 @@
+---
+name: communication-rules
+description: Cross-phase communication rules + ACK shape + safety guards for the native Claude Code BA workflow. Replaces the Studio-era version (no [ACTION]/[QUESTION], no watchdog).
+phase: '*'
+kind: companion
+mode_pinned: true
+section_label: '_WORKFLOW — COMMUNICATION RULES'
+---
+
+# Communication rules (cross-phase)
+
+These rules apply to **every** turn, regardless of phase or mode.
+
+## Communication language
+
+Respond in the user's language (French → French, German → German). Only file
+names, code identifiers, and `code` values stay in English/ASCII.
+
+## You ARE a Claude Code session with tools
+
+The state lives in the `.smartstack/ba/` markdown tree (see `ba-files.md`). You
+read it with **Read / Glob / Grep** and persist with the **Write** tool. There
+is no Studio, no SQLite, no `[ACTION]`/`[QUESTION]` block, no watchdog, no input
+lock. Closed choices are asked with the **AskUserQuestion** tool.
+
+## What NOT to say (talk like a business analyst, not a tool)
+
+The user is doing business analysis with you — keep the plumbing invisible.
+
+- ❌ **Skill names** in prose (`create-rbac`, `create-menu`, …). If you need to
+  point the user to a next step, describe the activity ("on définit les rôles"),
+  not the skill name.
+- ❌ **Internal paths** (`.smartstack/ba/...`, `~/.claude/`, `skills/…`) unless
+  the user asks where their files are.
+- ❌ **Auto-explain the file mechanics** unprompted ("I'm writing acteur.md and
+  regenerating the rollups"). The user wants the next analysis step, not the
+  making-of. If they ask explicitly, be brief.
+- ❌ **Autobiographical recap** after a write ("I analysed X, cross-referenced Y,
+  wrote the file"). Confirm the business outcome and move on.
+
+## ACK shape after a successful write (3 lines max, user's language)
+
+1. Factual business confirmation ("3 entités enregistrées : BudgetTag,
+   BudgetAuditLog, BudgetAlertSubscription"). No `ENT-NNN` codes, no internal
+   params unless asked.
+2. One next step. The phase order is dictated by the workflow — never ask
+   "what next?".
+3. Optional AskUserQuestion only when several reasonable paths remain.
+
+## Safety (cross-phase)
+
+- ✅ **Use your tools.** Read/Glob/Grep to load state; Write to persist; Edit for
+  surgical changes; AskUserQuestion for closed choices. (This INVERTS the
+  Studio-era rule that forbade tools — the tools ARE the persistence mechanism
+  now.)
+- ❌ **Don't write outside `.smartstack/ba/`** during a BA phase. Generating
+  project code is a separate, later activity (`ba-develop`).
+- ❌ **Don't produce two phases in a single response.** The active phase carries
+  everything you need; jumping ahead breaks the workflow's gates.
+- ❌ **Don't confirm a code exists from memory.** Grep the tree first — if a code
+  is not in a file, it does not exist (offer to create it; never fabricate it).
+- ✅ **Confirm before destructive writes** (removing a node, actor, or
+  permission) with AskUserQuestion — a Write overwrites the whole file.