You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is the third periodic audit for DungeonMaster. Every tenth spec is reserved for an architectural audit that reviews the previous nine specs, checks compliance with engineering standards, identifies gaps, and recommends the next phase.
This audit covers specs #11 through #19 and assesses the overall health of the project before proposing specs #21–#29. (Spec #20 is the previous audit; this document audits that audit's findings.)
Rationale: Players need slash commands to participate in gameplay (/play, /roll, /cast-spell, /describe-action). Narrative output routes through Ollama (spec #13) and triggers AI actions (spec #15). This is the gateway to actual Discord sessions.
Rationale: Spec #19 defines enemies and encounters. Spec #16 defines dice rolling. Spec #22 ties them together: initiative rolls, turn order, attack resolution, damage calculation, loot distribution. This is the core of a Dungeons & Dragons session.
Key Deliverables:
Initiative system (d20 roll vs enemy CombatStats)
Turn order queue (PC → Enemy → PC, priority by initiative)
Attack action: player character vs enemy; hit/miss determination; damage calculation
Loot rolling: LootTable.DropChance gates reward; roll for quantity/rarity
End-of-combat cleanup: move defeated enemies to Encounter.ResolvedEnemies
API endpoints: POST /api/encounters/{id}/start-combat, POST /api/encounters/{id}/player-attack, POST /api/encounters/{id}/resolve-combat
Rationale: Human DM needs a single pane of glass: active encounters, narrative log, pending AI actions (awaiting approval), player character status, loot distribution. All read-only except for override buttons.
Key Deliverables:
Dashboard layout: 4-panel (Encounter Status | Narrative Log | AI Actions Pending | Party Overview)
Encounter Status panel: active enemies, HP bars, turn order indicator
Rationale: Players need a persistent view of their character: HP, AC, ability scores, equipment (from spec #6), spells (from spec #9), conditions (poisoned, charmed, etc.). Also the hub for /roll, /cast-spell actions.
Priority: 🟡 HIGH Depends on:#13 (Narrative), #22 (Battle System), #24 (Player Character UI)
Rationale: A unified audit log of everything that happened: narrative prompts, AI responses, dice rolls, attack results, loot awards, spell casts, condition changes. Enables session replay, post-game analysis, dispute resolution (if a roll is questioned).
Key Deliverables:
CombatLogEntry entity: timestamp, actor (PC name/Enemy name/AI DM), action type (Cast Spell / Attack / Describe Action / Narrative), details (JSON), result
Immutable log (no deletes, only appends)
API endpoints: GET /api/encounters/{id}/log, GET /api/campaigns/{id}/audit-log
Search/filter API: by actor, by action type, by date range
Rationale: After a session, Human DM wants a summary: what happened, who died, loot gained, XP awarded. Exportable as Markdown for record-keeping or sharing with players.
API endpoint: GET /api/campaigns/{id}/sessions/{sessionId}/summary
No real-time update (generate on-demand, cache for 1 hour)
Integration test: generate summary from sample encounter, verify Markdown structure
bUnit test: component state binding
Watch Points:
Markdown XSS (sanitize narrative log before rendering)
PDF generation latency (may take 2–5 seconds for long sessions)
Cloud storage for archived PDFs (if retention is months/years)
Priority Tier 3 — Advanced Features (Nice-to-Have, Depends on Tier 2)
Spec #27 — Inventory Management & Equipment System
Priority: 🟢 MEDIUM Depends on:#6 (Item Catalog), #24 (Player Character UI)
Rationale: Players carry items; items have weight, rarity, special properties. Inventory screen shows what's equipped, what's in the backpack, weight limit. Spells are items (spec #6SpellItem), weapons are items, armor is items. This spec wires them together.
Key Deliverables:
PlayerInventory entity: PC → Collection of InventorySlot (item, quantity, equipped flag)
Priority: 🟢 MEDIUM Depends on:#13 (Narrative), #15 (AI Action System)
Rationale: NPCs (non-player characters) are story drivers: merchants, quest-givers, allies, enemies. Companions are NPCs that travel with the party. This spec defines their entities, AI behavior (spec #15 integration), and interaction flows.
Rationale: Campaigns are driven by quests. This spec defines how Human DM creates quests, how AI DM presents them to players, how the system tracks completion. Tight integration with Ollama (spec #13) for narrative quest hooks.
Key Deliverables:
Quest entity: title, description, objectives (list of QuestObjective), reward (XP / gold / items), status (active / completed / failed)
QuestObjective entity: description, progress tracking (boolean or numeric), success condition
PlayerQuestProgress entity: player → quest → objective progress
Human DM UI: QuestBuilder (Markdown editor for description, objective designer, reward calculator)
AI integration: INarrativeEngine accepts active quest list; Ollama references quests when generating narrative
Plugin System (custom spells, homebrew rules, third-party integrations)
Analytics & Telemetry (session duration, player engagement, feature usage)
Architectural Notes
Human DM Authority — Final Directive
All AI-facing specs (#13, #15, #19, #21, #22, #28, #29) embed a non-negotiable rule:
The human Dungeon Master has final authority over the AI Dungeon Master. AI outputs (narrative, actions, rulings) are proposals. Human DM may approve, modify, or reject any AI decision in real-time.
This is enforced via:
Approval Gates: AI action execution paused until Human DM clicks Approve (when AutoApproveNarrative = false)
Override Mechanisms: Human DM can cancel pending actions, reroll dice, change encounter state
Audit Trail: All approvals/rejections logged in CombatLogEntry with Human DM identity
Escape Hatch:/override command allows Human DM to inject narrative or rules directly
Timeline: 8–10 weeks (parallel work by Rory, Clara, Danny)
Success Criteria: Players can run a full session end-to-end (campaign → combat → loot → summary)
Compliance Verdict: 🟢 PASS
The project maintains rigorous architectural discipline. All engineering standards from copilot-instructions.md are honoured or in-flight. The main risks are documentation gaps (spec #19) and cross-spec naming drift (action enums), both easily resolved before Phase B begins.
Recommendation: Approve specs #21–#29 as drafted. Resolve issues #4, #6 and spec #19 documentation before implementing specs #21+.
Spec #30 — Audit: Specs #21–#29 + Full Compliance Review
Overview
This is the third periodic audit for DungeonMaster. Every tenth spec is reserved for an architectural audit that reviews the previous nine specs, checks compliance with engineering standards, identifies gaps, and recommends the next phase.
This audit covers specs #11 through #19 and assesses the overall health of the project before proposing specs #21–#29. (Spec #20 is the previous audit; this document audits that audit's findings.)
Current Project State:
Compliance Review (Specs #1–#19)
Standards Audit Summary
dotnet buildreports 0 warnings, 0 errorsInitializeCampaignCommand,GetCampaignQuery).razor.cscounterparts (TitleBar, ThemeSelector, RightPanel, ImagePicker, LoginDisplay).csprojIRepository<T>interfaces; EF Core implementations in Infrastructure--color-*,--spacing-*)bigintforDiscordChannelId; EF converter handlesulong→longIssues Status — Specs #1–#19
INarrativeEngineinterface, Ollama HTTP clientIAiActionDispatcher, action handler registryRandomNumberGenerator); integration tests pendingSpawnEncounterAction; core logic readyCompliance Verdict
🟢 PASS — The project maintains high architectural discipline:
AUTHENTIK_AUTHORITYenv variable (spec [SPEC] Authentication & Authorization (OIDC / Authentik) #12 implementation incomplete for test environment)TriggerEncounterActionvsSpawnEncounterAction)Open Technical Debt
Critical Blockers (must close before Specs #21+)
Medium Priority (address in Specs #21–#29)
ulong→longDiscord ID conversion in auth/logging layersAiActionType) and handler registryProposed Specs #21–#29
These nine specs complete the Discord game session loop and expose management UI for human DMs.
Priority Tier 1 — Core Session Loop (Critical Path)
Spec #21 — Discord Gameplay Commands & Narrative Flow
Priority: 🔴 CRITICAL
Depends on: #13 (Narrative Engine), #15 (AI Action System)
Blocked by: #4, #6, #7 (Campaign initialization)
Rationale: Players need slash commands to participate in gameplay (
/play,/roll,/cast-spell,/describe-action). Narrative output routes through Ollama (spec #13) and triggers AI actions (spec #15). This is the gateway to actual Discord sessions.Key Deliverables:
/play {action},/roll {dice},/describe-action {description}POST /api/campaigns/{id}/narrative-requests,GET /api/campaigns/{id}/narrative-historyWatch Points:
Spec #22 — Battle System (Turn Order, Initiative, Encounter Resolution)
Priority: 🔴 CRITICAL
Depends on: #16 (Dice Engine), #19 (Enemy System)
Blocks: Nothing (but enables session gameplay)
Rationale: Spec #19 defines enemies and encounters. Spec #16 defines dice rolling. Spec #22 ties them together: initiative rolls, turn order, attack resolution, damage calculation, loot distribution. This is the core of a Dungeons & Dragons session.
Key Deliverables:
LootTable.DropChancegates reward; roll for quantity/rarityEncounter.ResolvedEnemiesPOST /api/encounters/{id}/start-combat,POST /api/encounters/{id}/player-attack,POST /api/encounters/{id}/resolve-combatCombatRound,CombatAction,InitiativeEntryentitiesWatch Points:
Spec #23 — Campaign Dashboard UI (DM Oversight)
Priority: 🟡 HIGH
Depends on: #3 (UI Shell), #13 (Narrative Engine), #22 (Battle System)
Rationale: Human DM needs a single pane of glass: active encounters, narrative log, pending AI actions (awaiting approval), player character status, loot distribution. All read-only except for override buttons.
Key Deliverables:
IAiActionproposals (e.g., SpawnEncounterAction, CastSpellAction) with Approve/Reject buttonsWatch Points:
Spec #24 — Player Character UI (Character Management)
Priority: 🟡 HIGH
Depends on: #3 (UI Shell), #9 (Character Sheet Setup)
Rationale: Players need a persistent view of their character: HP, AC, ability scores, equipment (from spec #6), spells (from spec #9), conditions (poisoned, charmed, etc.). Also the hub for
/roll,/cast-spellactions.Key Deliverables:
Watch Points:
Priority Tier 2 — Audit & History (Data Integrity)
Spec #25 — Combat Log & Event Timeline
Priority: 🟡 HIGH
Depends on: #13 (Narrative), #22 (Battle System), #24 (Player Character UI)
Rationale: A unified audit log of everything that happened: narrative prompts, AI responses, dice rolls, attack results, loot awards, spell casts, condition changes. Enables session replay, post-game analysis, dispute resolution (if a roll is questioned).
Key Deliverables:
CombatLogEntryentity: timestamp, actor (PC name/Enemy name/AI DM), action type (Cast Spell / Attack / Describe Action / Narrative), details (JSON), resultGET /api/encounters/{id}/log,GET /api/campaigns/{id}/audit-logWatch Points:
Spec #26 — Session Playback & Campaign Summaries
Priority: 🟡 MEDIUM
Depends on: #25 (Combat Log)
Rationale: After a session, Human DM wants a summary: what happened, who died, loot gained, XP awarded. Exportable as Markdown for record-keeping or sharing with players.
Key Deliverables:
CombatLogEntry, builds narrative summaryGET /api/campaigns/{id}/sessions/{sessionId}/summaryWatch Points:
Priority Tier 3 — Advanced Features (Nice-to-Have, Depends on Tier 2)
Spec #27 — Inventory Management & Equipment System
Priority: 🟢 MEDIUM
Depends on: #6 (Item Catalog), #24 (Player Character UI)
Rationale: Players carry items; items have weight, rarity, special properties. Inventory screen shows what's equipped, what's in the backpack, weight limit. Spells are items (spec #6
SpellItem), weapons are items, armor is items. This spec wires them together.Key Deliverables:
PlayerInventoryentity: PC → Collection ofInventorySlot(item, quantity, equipped flag)InventorySlotproperties: item FK, quantity (for potions, ammo), weight, equipped(STR * 15) pounds(D&D 5e rule)GET /api/characters/{id}/inventory,POST /api/characters/{id}/inventory/equip/{slotId},DELETE /api/characters/{id}/inventory/{slotId}Watch Points:
Spec #28 — NPC & Companion System
Priority: 🟢 MEDIUM
Depends on: #13 (Narrative), #15 (AI Action System)
Rationale: NPCs (non-player characters) are story drivers: merchants, quest-givers, allies, enemies. Companions are NPCs that travel with the party. This spec defines their entities, AI behavior (spec #15 integration), and interaction flows.
Key Deliverables:
Npcentity: id, name, description, disposition (helpful / neutral / hostile), loot table (from spec feat: Item Catalog — custom items, spells, weapons, and armor #6), AI behavior linkCompanionentity: NPC + player relationship (affinity score 0–100, can turn hostile)NpcInteractionentity: PC → NPC, interaction history (talked to, fought, traded)INpcBehaviorinterface for scripted/dynamic NPC actionsGET /api/npcs,POST /api/encounters/{id}/spawn-npc/{npcId},POST /api/characters/{id}/companions/talk-to-npc {name}→ narrative request routed to Ollama with NPC contextWatch Points:
Spec #29 — Quest & Objective Tracking
Priority: 🟢 LOW
Depends on: #13 (Narrative), #21 (Gameplay Commands)
Rationale: Campaigns are driven by quests. This spec defines how Human DM creates quests, how AI DM presents them to players, how the system tracks completion. Tight integration with Ollama (spec #13) for narrative quest hooks.
Key Deliverables:
Questentity: title, description, objectives (list ofQuestObjective), reward (XP / gold / items), status (active / completed / failed)QuestObjectiveentity: description, progress tracking (boolean or numeric), success conditionPlayerQuestProgressentity: player → quest → objective progressINarrativeEngineaccepts active quest list; Ollama references quests when generating narrative/quest-statusshows active quests;/complete-objective {quest_id} {objective_id}(Human DM only)GET /api/campaigns/{id}/quests,POST /api/campaigns/{id}/quests,PATCH /api/campaigns/{id}/quests/{questId}/progressWatch Points:
Recommended Execution Order
Specs should be implemented in dependency-first order to maximize parallelism and prevent blocking:
Phase A — Unblock Critical Tech Debt (Immediate)
Phase B — Core Session Loop (Weeks 1–3)
Phase C — History & Audit (Weeks 4–5, parallel with Phase B)
Phase D — Advanced Features (Weeks 6–8, after Phase B)
Parallelism Strategy:
Next Audit
Spec #40 will audit specs #31–#39. Recommendations for those specs:
Architectural Notes
Human DM Authority — Final Directive
All AI-facing specs (#13, #15, #19, #21, #22, #28, #29) embed a non-negotiable rule:
This is enforced via:
AutoApproveNarrative = false)CombatLogEntrywith Human DM identity/overridecommand allows Human DM to inject narrative or rules directlyCore/Infrastructure Separation
Specs #21–#29 must continue this discipline:
CombatRound,Initiative,QuestProgress) inDungeonMaster.CoreCombatRoundRepository,QuestRepository) inDungeonMaster.InfrastructureDungeonMaster.Bot(not Core)DungeonMaster.Infrastructure(not Core)CQRS Without MediatR
Specs #21–#29 continue the direct-handler pattern:
InitializeBattleCommandHandler,CastSpellCommandHandler,CreateQuestCommandHandlerGetBattleStatusQueryHandler,GetQuestLogQueryHandler.squad/decisions/inbox/)Custom CSS Only
All UI specs (#23, #24, #27, #28, #29) must use:
:rootand theme overrides).razortemplate only,.razor.cslogic)Summary of Findings & Next Steps
Key Achievements (Specs #1–#19)
Critical Gaps (Must Resolve First)
TriggerEncounterActionvsSpawnEncounterAction); resolve before Audit: Specs #21–#29 Compliance + Next Directions #21Next Phase (Specs #21–#29)
Compliance Verdict: 🟢 PASS
The project maintains rigorous architectural discipline. All engineering standards from
copilot-instructions.mdare honoured or in-flight. The main risks are documentation gaps (spec #19) and cross-spec naming drift (action enums), both easily resolved before Phase B begins.Recommendation: Approve specs #21–#29 as drafted. Resolve issues #4, #6 and spec #19 documentation before implementing specs #21+.