ERP_<MODULE>.md — template

Copy to the root of the customer's repo as ERP_<MODULE>.md (e.g. ERP_CRM.md). Keep every section, in this order, even when one is empty ("none — because …"), so any agent can read any module's file without learning a new layout. Write the content in the customer's words.

# <What the customer calls it> — <module id>

> **Agents: before acting on this file, read `dodil://erp/build` (or `dodil://build`,
> `dodil guide`, or https://blog.dodil.io/modules/lifecycle.md).** Start every session with Status, People and
> Change requests below — this file, not your memory, is the project's state. Changes to what is
> written here go through the change-request steps: questions → impact → yes → CR → work.
> Template v3 — sections: Status · People · Environments · Frame · Actors · Stories · Workflows ·
> Processes · Scenarios · Deviations · Entities · Master data · Jobs · Seams · Screens ·
> Reference diff · Change requests · Decisions.
> If any is missing, add it from https://blog.dodil.io/modules/template.md before other work.

Reference: /modules/<id>/spec.yaml v<n>

## Status
- Phase: <0–9>   Design: draft | signed off <YYYY-MM-DD> by <name>
- Live: <what is live, version, date — or "nothing yet">
- In progress: <CR-n / build step — on the test copy>
- Waiting on the customer: <question, or "nothing">
- Next step: <one line>

## People
| Who | Role in the business | Involvement | Words they use | Since |
|---|---|---|---|---|
| <name> | <owner / office manager / developer> | decides technical calls / weighs in on <process, screens, data, setup> | <"app", "the list"> | <YYYY-MM-DD> |

## Environments
| | Test copy | Live |
|---|---|---|
| Bucket | <customer>-dev | <customer> |
| App | localhost:<port> / <customer>-dev | <customer> — <url> |
| Sign-in pool | <customer>-dev | <customer> |
Local `.env` → test copy only. Live credentials: secret references in `.dodil/deploy.yaml`.

## Frame
- The system this belongs to: <customer's name for it>
- Repo: <repo>     (pool, bucket and app: see Environments)
- Reused from existing modules: <pool, bucket, business partner, ...>
- Other modules on the roadmap, in order: <...>

## Actors
| Actor | Does | Sees | Permissions |
|---|---|---|---|

## Stories
### Person
- **<ID>** · As a <actor>, I want <...>, so that <...>.
  Given <...> · When <...> · Then <...> · Screen: <...>
### System
- **<ID>** · <Trigger>, the system <...>, so that <...>.
  Given <...> · When <...> · Then <...> (incl. what happens on a re-run)
### Integration
- **<ID>** · When <...>, <...> in <other module>. Owner: <module>.

## Workflows
Process: <module> v1
### <entity>
States: <state>, <state>, <state>
Terminal: <state>, <state>
| Key | From | To | Who | Gate / requires | Effect | Timer | Approval |
|---|---|---|---|---|---|---|---|
| <draft_invoice> | none | <draft> | <biller> | | <a draft with no number> | | |

## Processes
The signed BPMN: generated from the reference plus the change list, never hand-edited. Files live in
`processes/` beside this file; `processes/<process>.changes.yaml` is the machine form of Deviations.
| Process | PCF | Reference (brick@tag) | Signed version | File | sha256 | Signed by, date |
|---|---|---|---|---|---|---|
| <Employee onboarding> | <10469> | <brick-hr@v0.4.0> | <v1> | processes/<onboarding>.bpmn | <sha256 of the file> | <name, YYYY-MM-DD> |

## Scenarios
Each story with a Given/When/Then, as a path through the process (the choices at each gateway).
| ID | Story | Path (choices) | Ends in | Status |
|---|---|---|---|---|
| <HR-01> | <in their words> | <Gateway_worker_type: freelancer_company> | <ready for day one> | agreed / built / passing |

## Deviations
Every difference from the reference, at its depth (1 configure · 2 extend · 3 own), with the
best-practice warning the customer accepted. Signed before it is built.
| # | Element | Change | Depth | Warning (source) | Accepted by, date | Status |
|---|---|---|---|---|---|---|
| D-1 | <Task_onboarding_contract> | <only a director signs> | 1 | <none / the warning and its standard: or typical: source> | <name, YYYY-MM-DD> | agreed / built |

## Entities
| Entity | Meaning | Natural key | Key attributes | Relationships | Table |
|---|---|---|---|---|---|

## Master data
- Owns (sole writer): <entity — table>
- References: <entity — owner module — join column>

## Jobs
| Story | Trigger | What runs | Where it runs | Idempotent how |
|---|---|---|---|---|

## Seams
| Story | Other module | Owner | Rule |
|---|---|---|---|

## Screens
| Screen | Stories | Actors |
|---|---|---|

## Reference diff
The summary of Deviations, in the customer's terms.
- Kept: <...>
- Changed: <what, and why — in the customer's terms>
- Dropped: <...>
- Added: <...>

## Change requests
Each CR names the element ids it touches and produces a new signed process version.
| CR | Date | Asked by | What | Touches (element ids, stories, tables) | Process version | Status |
|---|---|---|---|---|---|---|
| CR-1 | <YYYY-MM-DD> | <name> | <in their words> | <Task_deal_site_visit, S-03, crm_deals.visit_at> | <v1 -> v2> | agreed / on test copy / live <date> |

## Decisions
- <YYYY-MM-DD> <decision> — <reason> — <who>

The Workflows format (what erp-compose bpmn --from ERP_<MODULE>.md reads)

Written during Discover and Show; it is what the customer's diagram is drawn from, so it must parse (erp-platform 0.8; a malformed table fails with its line number). Under ## Workflows:

• Process: <id> v<n> (optional): the process id and version; default the file name (ERP_INVOICING.md → invoicing) and v1.
• ### <entity> (snake_case), then States: a, b, c, then optionally Terminal: b, c, then ONE table. A blank line ends the table. Prose between tables is allowed.
• Columns, any order; From, To and Who required: Key (a slug, frozen once signed → Task_<key>; derived <entity>_<from>_to_<to> if left out, but write it) · Step (the task's name in their words; generated if left out) · From (none = created; several separated by commas) · To (several = an outcome choice, Gateway_<key>__if) · Who (an actor from ## Actors, matched by slug, or system) · Gate / requires · Effect · Timer (ISO 8601 P7D or words → Timer_<key>) · Approval (yes). A | inside a cell is written /.
• A step that keeps its state (To = From, or To empty): drawn in its state's sequence, in row order. With a Gate it is OPTIONAL: Gateway_<key>__if → the step → Gateway_<key>__if_end.
• Terminal: a state the process may end in. With exits, it is a choice between ending and its exits; a state a row enters that has no exit and is not Terminal is an error.
• External actors: (external) after the name in the Actors table (| Client contact (external) | … |). Their rows are steps the process WAITS on, in their own lane, with a message from their own pool. It changes no state unless the row says so.

## Workflows
### invoice
States: draft, issued, void
Terminal: issued, void
| Key | From | To | Who | Gate / requires | Effect | Timer | Approval |
|---|---|---|---|---|---|---|---|
| draft_invoice | none | draft | biller | | a draft with no number | | |
| issue_invoice | draft | issued | biller | at least one line | numbered, frozen | | |
| chase | issued | | collector | overdue and outstanding > 0 | reminder sent | P7D | |
| void_invoice | issued | void | approver | no allocations | reversing journal | | yes |