browser/openspec/changes/integrate-real-scum-ops-workflows/specs/scum-workflow-automation/spec.md

ADDED Requirements

Requirement: Sequential workflow definitions

The system SHALL define SCUM workflows as ordered typed steps with dependencies, inputs, permissions, safety gates, execution transport, confirmation, retry policy, and blocking states.

Scenario: Workflow starts with dependencies

• WHEN a workflow instance is created for a server instance
• THEN platform evaluates dependency steps and dispatches only the first runnable step whose prerequisites are satisfied

Scenario: Step depends on projection freshness

• WHEN a step requires fresh player, squad, vehicle, flag, or position projections
• THEN platform runs or waits for the required observation workflow before dispatching the dependent write or UI-facing step

Requirement: One-by-one execution per server

The system SHALL execute SCUM workflow steps one by one per server instance when steps mutate game state, while allowing safe read observation steps to run with bounded concurrency.

Scenario: Two write workflows are queued

• WHEN two player mutation or gift-delivery workflows target the same server instance
• THEN platform dispatches the next state-changing step only after the prior state-changing step reaches confirmed, failed, blocked, cancelled, or unknown terminal state

Scenario: Read observation workflows are queued

• WHEN multiple read observation steps target players, squads, vehicles, and flags
• THEN platform may batch or parallelize them within declared row, timeout, and concurrency limits without violating run channel priority

Requirement: Integrated SCUM workflow library

The system SHALL provide first-party workflow templates for common SCUM operations that combine real data reads, typed writes, and product-state updates.

Scenario: Player profile refresh workflow

• WHEN an operator refreshes a player profile
• THEN platform runs login evidence sync, player SCUM.db lookup, economy lookup, squad membership lookup, current position lookup, and projection update as one tracked workflow

Scenario: Player correction workflow

• WHEN an operator approves a player correction
• THEN platform runs safety check, before-value read, RCON or DB mutation, confirmation read, projection update, and audit completion in order

Scenario: Gift delivery workflow

• WHEN a gift grant becomes eligible by schedule, player type, achievement, or manual approval
• THEN platform runs eligibility check, inventory/reward operation, player notification, confirmation read/result, and grant-state transition in order

Scenario: Territory risk workflow

• WHEN an operator opens squad or flag governance
• THEN platform can run squad roster refresh, flag ownership refresh, member-position overlay, stale-owner detection, and risk-signal projection without direct browser database access

Scenario: Vehicle inventory workflow

• WHEN an operator requests vehicle inventory/map refresh
• THEN platform runs vehicle query, coordinate projection, owner/nearby squad enrichment where available, stale vehicle marking, and map overlay update

Scenario: AI configuration workflow

• WHEN an operator asks AI to configure or tune the SCUM plugin
• THEN platform gathers allowed plugin config fields, generates a reviewable diff, validates the diff, dispatches approved writes through existing config approval, and reports completion

Requirement: Workflow status and audit evidence

The system SHALL expose workflow status, current step, blocker reason, retry count, confirmation status, stale data references, and audit references through safe product APIs.

Scenario: Workflow blocks on missing run

• WHEN a workflow step requires bound run execution but no current run session can claim the capability
• THEN platform marks the workflow blocked with a safe reason and does not leak machine paths, tokens, sockets, or protected payload text

Scenario: Workflow completes

• WHEN all required steps reach terminal success and confirmations pass
• THEN platform marks the workflow confirmed, links audit evidence, and updates the relevant player, squad, vehicle, flag, gift, or configuration projection

Requirement: Retry without duplicating game effects

The system SHALL apply idempotency keys, fencing tokens, and confirmation reads so retries do not duplicate gifts, duplicate currency updates, or overwrite newer player state.

Scenario: Run loses connection after command dispatch

• WHEN run disconnects after a state-changing command may have executed
• THEN platform performs a confirmation read before deciding whether to retry, mark unknown, or mark confirmed