# Engagement layout template

This is the layout each engagement repository fills. It is a template
only: **no engagement is ever added to this repository**, real or
fictional (C-5).

## Where an engagement lives

Every engagement, real or fictional, lives in its own repository, cut
from a tagged release of `rosetta-deploy`, with this repository as its
`upstream` remote (DT-RX-038 Q-C-bis-3):

- **Real customers:** a private repository on GitSoma, inside the
  Salesforce boundary. Never in the `vernonkeenan` GitHub org.
- **Simulations and fictional customers:** a private repository in the
  `vernonkeenan` org, set up the same way.

To start one:

1. Create an empty private repository. Clone this repository at a
   release tag, rename its remote to `upstream`, add the new repository
   as `origin`, and push.
2. Copy `customer/_template/` to `customer/<customer>/` in the new
   repository and fill it there. A simulation says in
   `customer/<customer>/README.md` that it is fictional.
3. Change nothing outside `customer/<customer>/`. Then merging the next
   tag from `upstream` conflicts with nothing, and the library's
   generated folders stay as Rosetta wrote them (C-1).

## CI in an engagement repository

The repository inherits the library's CI (`.github/workflows/ci.yml`).
Where its host runs GitHub Actions, set two things before the first pull
request, under Settings > Secrets and variables > Actions:

- **The repository variable `CUSTOMER_SCAN_ENGAGEMENT`:** the folder
  name, such as `northwind-traders` for `customer/northwind-traders/`.
  Without it, the `customer-scan` job takes the repository for the
  library and refuses the folder.
- **The repository secret `CUSTOMER_DENYLIST`:** the customer's own
  names and its people's names, one per line. They may appear inside
  `customer/<customer>/` and nowhere else, `contributions/` included.
  Without the secret, `customer-scan` fails. A simulation that the
  library itself names, such as Northwind Traders, leaves that name off,
  or merging the next tag from `upstream` fails.

Email addresses, phone numbers and other personal data still fail
inside the folder. Use `example.com` addresses and 555 numbers, or leave
them out.

## The layout

| Folder | Holds, in the engagement repository |
|---|---|
| `project-docs/` | The engagement's working documents: dossier, notes, requirements |
| `archaeology/` | The engagement twin (`twin.json`) and the archaeology run's notes, written by the archaeology deploy edition; the `CP/` and `ADR/` drafts are generated from the twin |
| `deliverables/` | What is delivered to `<customer>`: the Solution Thesis, and any SOW or Spec Manifest Rosetta compiles for it |
| `ADR/` | The engagement's own ADRs, as drafts that cite library ids |
| `CP/` | The engagement's own context patterns, as drafts that cite library ids |
| `background/` | What the team knows about `<customer>`: business, goals, landscape, constraints |
| `terminology/` | `<customer>`'s own terms and acronyms, mapped to the library's |

Each folder holds a `README.md` placeholder that says what goes in it.
Engagement files cite the library by id and release, such as
`cp-g-014` at `v0.1.0`, and never copy library files.

## In this repository

Only `customer/_template/` lives under `customer/`. A pull request that
adds any other folder under `customer/`, or any customer name or data
anywhere, is refused (C-5).