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