skara-brae-common/docs/openup/model/BUILD-CHECKLIST.md

# Skara Brae — EA Model Build Checklist (WI-2)

Version 1.0 (2026-10-03) · Prepared by COD per `design-wi-2-architecture-cleanup.md` §11.b.4.
Sources (authoritative, do not deviate): `docs/openup/requirements/use-case-model.md`,
`docs/openup/analysis-design/uc-realization-mapping.md` (§1 tree, §2 realization table),
`docs/openup/requirements/supplementary-specifications.md`, design note §3 (boundary rules).
Drift rule: markdown and model must agree; a mismatch is a defect fixed in the same cycle.

This checklist is written to be clicked through in EA **or** executed via
`scripts/openup/build-model.ps1` (then verified below). The per-discipline element lists
are complete: nothing outside them belongs in the WI-2 model.

---

## 0. Prerequisites (Windows machine — see model/README.md for why not Linux)

1. skara-brae-common checked out (branch `wi-2-openup-docs` or later).
2. EA installed and licensed. Copy the EA installation's empty-model template to the
   model home:
   `C:\Program Files\Sparx Systems\EA\EABase.eapx` → `docs/openup/model/skara-brae.eapx`
   (exact install path may differ; the file is the standard empty `.eapx` template.
   Do **not** derive the skeleton from keyfob-station's model — it carries keyfob content).
3. PowerShell 5.1+ (built into Windows) for the script path.

## 1. Model root

- Rename the default model root to **`Skara Brae`** (keyfob equivalent: single model root).

---

## 2. Requirements discipline

### 2.1 Package `Requirements`

Create package **`Requirements`** directly under the model root.

### 2.2 Package `Requirements / Vision`

- Notes: purpose statement source = `docs/openup/requirements/vision.md` (the markdown is
  the human-facing source; the model carries the product purpose in the package notes and
  links, not a full copy).

### 2.3 Package `Requirements / Use Case Model`

**Actors (exactly 3)** — type `Actor`, notes verbatim from the Actors table:

| Actor | Notes |
|---|---|
| `Player` | Authenticated user owning one or more characters (JWT role `player`). |
| `Administrator` | Player with elevated rights (`role = admin`); may view any user's and any character's resources read-only. |
| `Guest` | Unauthenticated caller; only register/login are open. |

**Use cases (exactly 12)** — type `UseCase`, names verbatim:

`UC-01 Register Account`, `UC-02 Authenticate`, `UC-03 Manage Characters`,
`UC-04 Browse Game Catalogue`, `UC-05 Train Stat`, `UC-06 Manage Equipment`,
`UC-07 Trade at Shop`, `UC-08 Run Adventure`, `UC-09 Heal at Temple`,
`UC-10 Practice Bard Song`, `UC-11 Study Magic`, `UC-12 Level Up at Review Board`.

Element notes: the UC's precondition line(s) verbatim from `use-case-model.md`; plus:
- UC-05 note appends: *includes Regenerate Resources.*
- UC-08 note appends: *includes Regenerate Resources, Resolve Combat. Exception: encounter
  references an unknown enemy → 500 (post WI-2; previously a panic). WI-2 design driver
  (`sb_core::adventure` extraction).*
- Include targets are **sub-flows, not use case elements** (only 12 UCs exist) — model the
  includes in the notes, **not** as `«include»` connectors.

**Associations (exactly 13)** — type `Association`, Actor → UseCase:

| Actor | Use cases |
|---|---|
| `Guest` | UC-01, UC-02 |
| `Player` | UC-03, UC-04, UC-05, UC-06, UC-07, UC-08, UC-09, UC-10, UC-11, UC-12 |
| `Administrator` | UC-03 (read-only) |

**Scenarios** — stored on each use case (`Scenarios` collection), types are EA's
`Basic Path` / `Alternate` / `Exception`. Naming and structuring rules used below
(also implemented in `build-model.ps1`):
- Markdown "Main success scenario" → scenario **Main Success Scenario** (`Basic Path`);
  its numbered list items become ordered **steps**, each step's **Actor** = the leading
  grammatical subject of the step text (`Player`/`Guest` → that actor; otherwise `System`).
- Markdown "**Scenario (x):**" block → scenario named **x** (`Alternate`); prose text goes
  into the scenario notes verbatim.
- Markdown "**Alternate flows:**" prose → one scenario **Alternate flows** (`Alternate`),
  prose verbatim in notes.
- Markdown "**Exception:**" prose → scenario **Exception** (`Exception`), prose verbatim.
- Precondition text rides on the scenario notes of the Main Success Scenario.
- UC-11 has no labeled main scenario in the markdown; its first listed scenario
  (view spellbook) serves as the Basic Path, the remaining "Scenario (x)" blocks as
  `Alternate`.
- Parenthetical actor remarks on a step text (e.g. UC-03 step 1 "(Admin may act for any
  user)") move to the scenario notes to keep the step actionable; the wording is kept.

| UC | Scenario (type) | Steps (Actor: text) / Notes |
|---|---|---|
| UC-01 | Main Success Scenario (Basic Path) | Guest: Guest submits name (3–32 chars) and password (≥ 6 chars). · System: System verifies the name is unused → 409 CONFLICT if taken. · System: System hashes the password (argon2), assigns the `player` role and the next id, persists the user. · System: System issues a JWT (HS256, `player` role) and returns `{token, user_id, name, role}`. |
| UC-01 | Alternate flows (Alternate) | Notes: name length invalid → 400; password too short → 400; name taken → 409; hashing/token failure → 500. |
| UC-02 | Main Success Scenario (Basic Path) | Guest: Guest submits name and password. · System: System finds the user (401 if unknown) and verifies the password hash (401 on mismatch). · System: System issues a JWT carrying the user's real role (`admin`/`player`) and returns `{token, user_id, name, role}`. |
| UC-02 | Alternate flows (Alternate) | Notes: unknown name or wrong password → 401 UNAUTHORIZED; token creation failure → 500. |
| UC-03 | Main Success Scenario (create) (Basic Path) | Notes: Admin may act for any user. · Player: Player submits character name, race, class for their user id. · System: System validates the target user exists (404) and the trimmed name is 1–32 chars (400). · System: System rolls stats (d6+5 base 6–16 per stat ± race modifiers), computes max HP/energy/nerve from class, grants starting gold (50) and level-1 class spells to casters. · System: System assigns the next character id, stores and persists the character; returns it fully. |
| UC-03 | list/view (Alternate) | Notes: Player lists their characters (Admin: any user's); the system applies Regenerate Resources to each returned character and returns them. Viewing one character applies regen then returns it. |
| UC-03 | Alternate flows (Alternate) | Notes: foreign user/character without admin role → 403 FORBIDDEN; user/character not found → 404; invalid name → 400. |
| UC-04 | Main Success Scenario (Basic Path) | Player: Player requests the catalogue: races, classes, items (optional type/quality/slot filters), enemies, or adventure zones. · System: System returns static game data loaded from `skara-brae-common` JSON (class info is enriched with `is_caster`). |
| UC-04 | Alternate flows (Alternate) | Notes: single item by unknown id → 404; filters may return an empty list (not an error). |
| UC-05 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player selects a training ground (strength / dexterity / constitution / intelligence / luck) and submits the stat name. · System: System applies Regenerate Resources. · System: System checks energy ≥ 1 and gold ≥ training cost (cost grows ~1.3× per 10 stat points). · System: System deducts 1 energy and the gold cost, increments the stat; constitution training recomputes max HP (current HP clamped). · System: System persists and returns `{success, message, character}`. |
| UC-05 | Alternate flows (Alternate) | Notes: foreign character → 403; character not found → 404; not enough energy → 422; not enough gold → 422; unknown stat name → 400. |
| UC-06 | Main Success Scenario (equip) (Basic Path) | Player: Player submits an item id from their inventory. · System: System moves the item from inventory to its slot; a previously equipped item in that slot returns to inventory. · System: System persists and returns the updated character. |
| UC-06 | unequip (Alternate) | Notes: Player submits a slot name; the system moves the equipped item back to inventory. |
| UC-06 | Alternate flows (Alternate) | Notes: foreign character → 403; character/item not found → 404; item not in inventory → 400; nothing equipped in slot → 400. |
| UC-07 | Main Success Scenario (buy) (Basic Path) | Player: Player views the shop: always-stocked items plus rotating stock (with quantities) alongside their inventory. · Player: Player submits `buy` + item id. · System: System checks gold ≥ price (422), and for non-always-in-stock items decrements the limited stock (410 GONE if 0). · System: System deducts gold, adds the item to inventory, persists character and stock; returns `{success, message, gold}`. |
| UC-07 | sell (Alternate) | Notes: Player submits `sell` + item id; system removes the first matching inventory item, pays half the item value, increments shop stock for non-permanent items. |
| UC-07 | Alternate flows (Alternate) | Notes: unknown action or item not owned (sell) → 400; item not found → 404; insufficient gold → 422; stock exhausted → 410. |
| UC-08 | Main Success Scenario (Basic Path) | Notes: Precondition: character exists and caller may act on it. · Player: Player requests an adventure for a zone (default `skara_brae_streets`). · System: System validates the zone (404) and applies Regenerate Resources. · System: System refuses incapacitated characters (HP ≤ 0 → 400) and characters with nerve below the zone cost (422); otherwise deducts the nerve cost. · System: System draws one enemy from the zone's weighted encounter table. · System: System resolves turn-based combat: open-ended d100 attack rolls, OB vs DB, RoleMaster crit tables with level-gap damage caps, active bard song effects, active spell damage/heal per round. · System: On player victory: XP and gold per the enemy definition, character HP set to the last round's defender HP, and loot dropped per-item chance rolls (only items existing in the catalogue). · System: On defeat: character HP set to 0; no rewards. · System: Spell-point upkeep is charged whenever a spell was active, win or lose. · System: System persists the character and returns `{zone, enemy, combat_log, loot}` (loot = item display names). |
| UC-08 | Alternate flows (Alternate) | Notes: foreign character → 403; character/zone not found → 404; incapacitated → 400; insufficient nerve → 422. |
| UC-08 | Exception (Exception) | Notes: encounter references an unknown enemy (data error) → 500 (post WI-2; previously a panic). |
| UC-09 | Main Success Scenario (Basic Path) | Player: Player requests healing, optionally `partial`. · System: System computes missing HP; full heals all, partial heals half (rounded up); cost = amount healed, minimum 1 gold. · System: System checks gold (422), deducts it, restores HP, persists; returns `{hp, max_hp, gold, healed: true}`. |
| UC-09 | Alternate flows (Alternate) | Notes: foreign character → 403; not found → 404; already at full HP → 400; insufficient gold → 422. |
| UC-10 | Main Success Scenario (Basic Path) | Notes: Precondition: character class is Bard. · Player: Player views available songs (level-gated, with combat effect descriptions) and the active song. · Player: Player submits a song id; system validates level requirement (422) and sets it active; returns `{success, message, active_song}`. |
| UC-10 | clear (Alternate) | Notes: submitting no song id clears the active song. |
| UC-10 | Alternate flows (Alternate) | Notes: non-Bard → 403; unknown song → 404; level too low → 422; foreign character → 403; not found → 404. |
| UC-11 | Main Success Scenario (view spellbook) (Basic Path) | Notes: Precondition: character belongs to a caster class (Mage→magician, Wizard, Conjurer, Sorcerer). Spell level = (character level / 3) + 1 — uncapped by code (level 100 → spell level 34); learn requests are validated to 1–7. · Player: Player requests their spellbook: caster class, current spell level, spell points, spells up to the achievable level (each marked known), and the learn-cost table for levels 2–7. |
| UC-11 | learn spell level (Alternate) | Player: Player submits a spell level (1–7). · System: System validates caster class (403), level range (400), level not above the character's current spell level (422), gold ≥ learn cost (422), and that new spells exist (400). · System: System deducts gold, adds all unknown spell ids of that level, recomputes and refills max spell points; returns `{learned_count, spell_points, max_spell_points, gold}`. |
| UC-11 | activate/clear active spell (Alternate) | Player: Player submits a spell id (or empty to clear). · System: System validates the spell is known (403), exists (404), and spell points suffice (422); deducts the spell's points and sets it active; returns `{active_spell, spell_points}`. |
| UC-12 | Main Success Scenario (Basic Path) | Player: Player requests a level-up. · System: System validates: below max level 100, XP ≥ 18·100·(level)² for the next level (i.e. `xp_for_level(next)`), gold ≥ 500·next level. · System: System deducts the gold cost, increments the level, recomputes and fully restores HP/energy/nerve and max spell points; persists; returns `{success, message, character}`. |
| UC-12 | Alternate flows (Alternate) | Notes: all of already at max level; not enough XP; not enough gold → 422. Foreign character → 403; not found → 404. |

**Diagram** `Skara Brae Use Case Overview` (type `UseCase`): place all 3 actors (left
column) and all 12 use cases (right grid).

### 2.4 Package `Requirements / Supplementary Specifications`

- One child element per top-level section of `requirements/supplementary-specifications.md`,
  type `Requirement`, name = `SS-<n> <section title>` with the section's content in notes:
  `1. Performance / Scalability`, `2. Reliability / Correctness`,
  `3. Quality Gates (per-commit acceptance)`, `4. Data`, `5. Security`,
  `6. Constraints`, `7. Usability / API`.
- `Trace` connectors from each `SS-n` element to the use cases the section names
  (the spec text cites the UCs; when it names none, leave untraced rather than guessing).

---

## 3. Analysis-Design discipline

### 3.1 Package `Analysis-Design`

Create package **`Analysis-Design`** under the model root (mapping §1 name — note:
keyfob uses `Analysis & Design`; here the mapping document says `Analysis-Design` —
follow the mapping).

### 3.2 Package `Analysis-Design / Architecture Overview`

- Notes: the dependency rule verbatim from `uc-realization-mapping.md` §2
  ("all controllers/entities above live in `sb-core`/`sb-shared` …; the single current
  violations (ShopService, HealingService, parts of MagicService in sb-api) are recorded
  as debt … stale docs are defects") + design note §3 boundary rules.
- Three cross-cutting elements (type `Class`, notes from the mapping's cross-cutting
  paragraph):
  1. `DomainError` — notes: `sb-core::error::DomainError` + `sb-api::routes::domain_status`
     (status mapping table, design note §4.1) realize the error paths of UC-05/06/08/12.
  2. `Constants` — notes: `sb-core::constants` realizes NFR "no magic numbers".
  3. `Responses` — notes: `sb-api::routes::responses` realizes NFR-19 (wire-format freeze).

### 3.3 Twelve realization packages

For **each** entry in `docs/openup/model/exports/uc-realizations.json`
(generated from mapping §2 — 12 packages, 36 elements):

1. Package `UC-<NN> Realization` under `Analysis-Design`.
2. Inside it, one `Collaboration` element named like the package, with a `Realization`
   connector (Collaboration → the use case element in `Requirements / Use Case Model`).
3. Inside it, one `Class` element per mapping row:
   - Name = analysis class (e.g. `AdventureService`).
   - Stereotype = `controller` / `entity` / `boundary` (mapping §2 column).
   - Notes = the mapping's *Design element* cell verbatim, plus the *Notes* cell
     (e.g. `` `sb-core::adventure::run_adventure` (**new, WI-2**) + `services::pick_enemy`
     → `Result` (WI-2) — takes injected rng; `DomainError` (WI-2)``).
4. One class diagram per realization package (name = package name), all its classes placed.

Element counts for verification: UC-01:3, UC-02:2, UC-03:4, UC-04:2, UC-05:3, UC-06:3,
UC-07:3, UC-08:5, UC-09:2, UC-10:3, UC-11:3, UC-12:3 — total 36.

---

## 4. Verification (design §11.d)

1. Model opens clean (no missing-package errors).
2. `Requirements → Use Case Model` shows exactly 3 actors + 12 use cases; every UC carries
   its Main Success Scenario plus the alternates/exceptions from the table above, with
   per-step actors.
3. Spot-check two scenarios against `requirements/use-case-model.md` (recommended: UC-08
   MSS — 9 steps, and UC-11 learn spell level — 3 steps).
4. 12 `UC-N Realization` packages exist under `Analysis-Design` with the element counts
   above; spot-check the UC-08 realization table against `uc-realization-mapping.md` §2.
5. Association count is 13; there are no `«include»` connectors (includes live in UC notes).

## 5. Export + commit (design §11.d.4–5)

1. Run `scripts/openup/export-model.ps1` → regenerates
   `docs/openup/model/exports/use-case-model.json`, `uc-realizations.json` and an XMI
   backup; confirm the diff is expected (`uc-realizations.json` must be unchanged in
   content — it was generated from the mapping markdown).
2. Save the model; commit `.eapx` + `exports/` + `scripts/openup/` together as one commit
   `openup: EA model WI-2 baseline` in **skara-brae-common**.

---

## 6. Enrichment (2026-10-03, after manual layout session) — SURGICAL only

The user laid out diagrams by hand in EA after the WI-2 baseline build. From here on the
model may only be touched by the two surgical scripts below — **never** re-run
`build-model.ps1` (it deletes and rebuilds the Requirements / Analysis-Design packages and
would destroy manual layout). Sources: `uc-realization-mapping.md` §2a (interactions) and
§3 (design component model).

### 6.1 Analysis associations — `scripts/openup/add-analysis-associations.ps1`

- Inside each `UC-NN Realization` package: Association connectors per mapping §2a
  (boundary→controller, controller→entity; UC-04 boundary→entity) — **24 associations**
  (UC-01:2, UC-02:1, UC-03:3, UC-04:1, UC-05:2, UC-06:2, UC-07:2, UC-08:4, UC-09:1,
  UC-10:2, UC-11:2, UC-12:2).
- 4 Dependencies `«uses»` from TrainingService, EquipmentService, AdventureService,
  ReviewBoard to `DomainError` (Architecture Overview) — the error paths of UC-05/06/08/12.
- DiagramLinks added to each package's existing class diagram so the connectors render
  WITHOUT touching any DiagramObject (manual layout preserved). Idempotent: existing
  connectors are skipped.

### 6.2 Design package — `scripts/openup/add-design-package.ps1`

- Creates `Analysis-Design / Design` (rebuilds only this package — agent-owned, contains
  no manual edits): 7 components (skara-brae-client, sb-api, sb-auth, sb-db, sb-core,
  sb-shared, sb-common) with traceability notes, 10 Dependency connectors, one Component
  diagram `Component Architecture` (layered layout, dependency rule inward).

### 6.3 Verification

1. 24 associations across realization packages (per-UC counts above); 4 `«uses»`
   dependencies to DomainError; still 0 `«include»` connectors.
2. `Design` package: 7 components, 10 dependencies, 1 diagram.
3. Baseline intact: 3 actors, 12 use cases, 12 realization packages, 13 actor-UC
   associations; Requirements tree untouched.
4. Manual layout preserved: the scripts add no/modify no DiagramObjects in existing
   diagrams (only the new `Design` diagram carries its own object layout).

### 6.4 Diagram image export — `scripts/openup/export-diagram-images.ps1`

Read-only on the model: renders 14 diagrams to PNG for the markdown documents
(`requirements/use-case-overview.png`, `analysis-design/uc-01..uc-12-realization.png`,
`analysis-design/component-architecture.png`). EA-15 findings baked into the script:
image methods live on **ProjectInterface** (not Repository); `PutDiagramImageToFile(id,
path, 0)` = PNG; the diagram must be `OpenDiagram`-ed first or a blank 241×151 stub is
written. Regenerate after model changes; renders reflect the manual layout.

---

## 7. Documentation restructure (2026-10-05, non-PSP effort)

The OpenUP markdown set was aligned to the blank templates (process-data repo,
`templates/openup/`) — no EA model change required: scenario content is unchanged,
reformatted only; the model's UC notes/actors already carry the brief descriptions the
template sections now expose. XMI backup added 2026-10-05 via manual EA export
(`exports/xmi-backup.xml`); the COM export path is broken in this EA 15 build
(`ExportPackageXMI` filename param declared as Object in the typelib — verified across
PowerShell/JScript/VBScript, arities 2–6; `ExportProjectXML` returns false silently).

Restructured to template form:
- `requirements/vision.md` — positioning tables, stakeholder summary, user environment,
  needs-and-features table (R1/R2), other product requirements.
- `requirements/use-case-model.md` — per-UC specification sections (Brief Description,
  Actor Brief Descriptions, Preconditions, Basic Flow, named Alternative/Exception
  subsections with numbered steps, Post-conditions, Special Requirements). Flow step
  text unchanged from version 1.0.
- `requirements/supplementary-specifications.md` — category tables with Priority and
  Use-Case columns + reverse Use Case Coverage Matrix; IDs unchanged; project-specific
  categories (Quality Gates, Data) kept, DOC-01 added.
- `test/quality-check-procedure.md` — migrated from Joplin (single content home);
  stale open items marked resolved (WI-1/WI-2).

New design content:
- `analysis-design/sequences/uc-01..uc-12.puml` + PNG renders — design sequences per
  realization (lifelines = analysis classes, messages = design elements; PlantUML per
  the layout style guide). Embedded in Architecture Notebook §9.3, indexed §9.5.
  EA import via PlantUML `-txmi` remains optional future work (workflow canon).