---
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.