Add SCUM operations workflow OpenSpec

2026-08-10 18:24:51 +08:00
parent ff34a20906
commit ba2b1a9d9f
8 changed files with 496 additions and 0 deletions
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-08-10
@@ -0,0 +1,105 @@
 ## Context
 The repository already has pieces of the SCUM integration: log ingest and game player projections, game client bridge commands and snapshots, protected SQL/RCON/program request dispatch, source RCON input fencing, AI config diffs, gift catalogs, player state patches, remote adapter declarations, and plugin manifest validation. The current product surface still exposes broad logs/terminal/config/history concepts and several SCUM pages are placeholder-like or depend on old snapshots instead of the current server's real SCUM.db and login logs.
 The reference `scum_robot` and `scum_run` projects show the operational direction: the executor beside the game server can read SCUM.db, parse SCUM logs, query users/vehicles/flags/groups, and issue RCON commands for fame/currency. This change adapts that idea to this platform's boundaries: Platform owns intent, validation, audit, workflow records, and local projections; plugins own game-specific declarations; run/agent owns local machine execution and observed facts. The browser never receives raw SQL, host paths, DSNs, credentials, run sockets, or raw protected request text.
 ## Goals / Non-Goals
 **Goals:**
 - Replace fake or placeholder SCUM data with real projections from login logs and the bound run/agent's SCUM.db observations.
 - Add richer integrated operations: player profile refresh, player correction, fame/currency edits, attribute/stat mutation such as `855`, gift delivery, vehicle inventory, squad/flag governance, realtime map overlays, AI config/draft assistance, and reconciliation.
 - Introduce a sequential workflow layer so multi-step SCUM operations execute predictably with dependencies, approval, safety gates, confirmation reads, idempotency, and audit evidence.
 - Keep internal logs, run channels, audit, source RCON, protected request fencing, lifecycle, and AI config approval intact while removing raw product-facing panels and APIs that invite unsafe manual operations.
 - Keep implementation ownership split across `platform/`, `platform_web/`, and `plugins/`; implementation work for the independent run repository must remain outside this repository.
 **Non-Goals:**
 - Do not re-add a `run/` source tree to this repository.
 - Do not expose arbitrary SQL/RCON/terminal/config editing in browser APIs or plugin pages.
 - Do not create billing, hosting sales, cloud provider workflows, or marketplace behavior unrelated to first-party game server management.
 - Do not treat `last_save_time` as online-state proof by itself.
 - Do not special-case SCUM lifecycle behavior in platform or run services; game-specific declarations stay in the SCUM plugin.
 ## Decisions
 ### 1. Split reads, writes, and workflows
 Realtime lists and maps use read observations. State-changing operations use typed operation declarations. Multi-step outcomes use workflows that compose observations and operations.
 Alternative considered: keep a single `protected.sql`/`database.request` escape hatch. That is too broad for recurring product features and makes it impossible to validate field-level safety, permissions, and confirmation in the UI.
 ### 2. Query the current service through bound run/agent
 SCUM.db is the real source for many facts, but only the run/agent next to the current service should read it. Platform will queue server-bound observation jobs using plugin-declared templates and persist typed results into local projections. Product pages read only projections.
 Alternative considered: platform directly connects to SCUM.db through a configured path or socket. That violates run/platform ownership and leaks machine-specific execution details into control-plane code.
 ### 3. Prefer RCON for game-supported writes
 Fame and currency updates follow the reference behavior using game commands such as `#SetCurrencyBalance` and `#SetFamePoints`. Database mutation is reserved for fields without a supported command path, such as declared player state/stat fields when the plugin marks them DB-only.
 Alternative considered: update all editable fields directly in SCUM.db. That increases corruption risk and bypasses the game server's own command semantics where they exist.
 ### 4. Add typed mutation templates instead of browser SQL
 The SCUM plugin will declare operation templates that include operation type, schema refs, transport, target, approval level, safety rules, before-value guards, affected-row bounds, and confirmation query keys. Platform validates requests against those declarations before creating run jobs.
 Alternative considered: let admins type SQL into a protected request panel. That remains useful only as an emergency platform-admin tool, not as the backing mechanism for product workflows.
 ### 5. Store projections and workflow records locally
 Platform needs local domain records for players, squads, members, vehicles, flags, current positions, observations, workflow instances, workflow steps, operation requests, and confirmations. These records power UI, API responses, stale-state visibility, idempotency, and audit.
 Alternative considered: have every page dispatch live run queries. That couples UI responsiveness to run connectivity, duplicates query logic, and creates stale-data ambiguity.
 ### 6. Remove raw product surfaces, not core plumbing
 The server detail experience should drop raw logs, terminal/RCON input, raw config workbench, and generic operation history. Internal log ingest, run log channels, audit records, source RCON execution, config diff approval, and lifecycle evidence remain available to services and typed workflow status.
 Alternative considered: hide the panels but leave old APIs as-is. That keeps unsafe product paths alive and makes plugin/UI contracts harder to reason about.
 ## Workflow Library
 The implementation should create these first-party workflow templates and execute them in this order as they become available:
 1. `scum.bootstrap-real-data`: verify run binding, declare SCUM.db/log sources, run schema probes, create observation cursors, and initialize stale projection records.
 2. `scum.player-refresh`: parse login evidence, query SCUM.db player/economy/squad/position facts, upsert player projection, and update freshness.
 3. `scum.world-refresh`: query squads, squad members, vehicles, flags, current positions, and observation checksums, then refresh map overlays.
 4. `scum.player-correction`: validate player/offline state, approve typed edit, execute RCON or DB mutation, confirm by readback, and update projection.
 5. `scum.gift-delivery`: evaluate schedule/eligibility, execute reward/notification, confirm result, and transition grant state.
 6. `scum.territory-audit`: refresh squad/flag/member data, detect stale owner/member/flag inconsistencies, and create reviewable risk signals.
 7. `scum.vehicle-audit`: refresh vehicle inventory, classify vehicle names, mark stale/missing observations, and update map inventory.
 8. `scum.ai-assist`: collect allowed fields, generate reviewable config diff or workflow draft, validate, approve, dispatch, and confirm.
 9. `scum.product-cleanup`: remove raw product panels/APIs and route users to typed workflow/status surfaces.
 Each workflow step records `serverInstanceId`, `workflowId`, `stepKey`, `source`, `capability`, `observedAt`, `receivedAt`, `sequence`, `checksum`, `attempt`, `status`, `safeSummary`, and audit references where applicable.
 ## Risks / Trade-offs
 - [Risk] SCUM.db schema varies across game versions. → Mitigation: add version/schema probes, per-query result schemas, unknown-field handling, and plugin versioned templates.
 - [Risk] SQLite reads can lock or lag during active server writes. → Mitigation: use bounded read-only execution, short timeouts, retry/backoff, and stale-state display instead of blocking product pages.
 - [Risk] DB mutations can corrupt player state. → Mitigation: prefer RCON, require offline/maintenance safety windows, before-value guards, max affected rows, backup/snapshot evidence, and read-after-write confirmation.
 - [Risk] Workflow retries can duplicate gifts or currency changes. → Mitigation: use idempotency keys, grant state locks, confirmation-before-retry, and unknown terminal states when execution cannot be proven.
 - [Risk] Removing raw panels may hide useful diagnostics. → Mitigation: keep internal logs/audit/run evidence and expose safe workflow status summaries rather than raw terminal/log/config tools.
 - [Risk] Run support lands in a separate repository. → Mitigation: define platform/plugin contracts here and track run-side implementation as an external dependency without adding run source here.
 ## Migration Plan
 1. Add platform domain/repository/API contracts for observations, projections, controlled operations, workflow instances, workflow steps, and confirmations.
 2. Extend SCUM plugin manifest and validator schemas for read observation templates and typed operation templates.
 3. Implement platform projection services for login logs and SCUM.db typed results, then wire job completion to projection updates.
 4. Implement workflow queue and first workflow templates behind server/plugin permissions.
 5. Replace SCUM plugin pages with projection-backed user, squad, vehicle, flag, map, gift, AI, and workflow views.
 6. Remove raw product panels and APIs after new typed workflow/status views are available.
 7. Coordinate run repository changes for local SCUM.db read templates and controlled operation execution; verify browser repo contracts with stubbed or mocked run results until the external run change lands.
 Rollback keeps projections and workflow records but disables dispatch of new workflow steps through feature/config gates. Raw internal logs, audit, and lifecycle services remain untouched.
 ## Open Questions
 - Exact SCUM.db field mapping for player attribute/stat field `855` must be confirmed against real server schema before declaring a production mutation template.
 - Whether DB-only player state mutations require full server stop or player-offline maintenance window depends on field category and must be recorded per operation template.
 - Vehicle type naming should prefer plugin/static mapping or platform-maintained trade-good mapping; this can start as unknown/fallback to entity class until verified.
 - Gift item delivery transport must be finalized per reward type: companion command, RCON command, or DB mutation with confirmation.
@@ -0,0 +1,34 @@
 ## Why
 The SCUM plugin currently mixes placeholder surfaces, broad management tools, and incomplete real-data plumbing, so player, squad, vehicle, flag, map, gift, and state-management features cannot be trusted as live operations data. We need to turn SCUM integration into a real server-operations cockpit driven by the bound run/agent and current SCUM server facts, while preserving AI-assisted configuration and replacing unsafe/manual panels with typed workflows.
 ## What Changes
 - Add real SCUM data ingestion workflows for login logs, SCUM.db read models, and platform-local projections for players, squads, vehicles, flags, positions, and observations.
 - Add controlled SCUM operations for player currency, fame, attribute/stat fields such as `855`, gift delivery, notifications, and maintenance-safe data mutations.
 - Add a typed workflow queue so platform can execute SCUM workflows one by one with approval, lease fencing, read-after-write confirmation, retry rules, stale-state handling, and audit evidence.
 - Expand integrated SCUM features beyond the current pages: player identity enrichment, squad/flag governance, vehicle inventory, map overlays, economy and gift lifecycle, risk signals, rollback snapshots, and AI operation recommendations.
 - Preserve AI assistant flows for quick plugin configuration and operations recommendations, but constrain AI output to reviewable typed diffs and allowlisted workflow requests.
 - Replace product-facing log viewer, management terminal, raw config workbench, and operation-history surfaces with workflow/status views that expose only approved typed operations and safe summaries.
 - **BREAKING**: Remove product-layer APIs and plugin page routes whose primary purpose is raw logs, terminal/RCON input, arbitrary config file editing, or generic operation history; internal log ingest, run channels, audit, lifecycle, source RCON, query bridge, and AI config approval remain.
 ## Capabilities
 ### New Capabilities
 - `scum-real-data-projections`: Real SCUM login-log and SCUM.db observation pipelines, typed query result validation, local platform projections, freshness/staleness behavior, and read-only product surfaces.
 - `scum-controlled-operations`: Typed SCUM write operations using RCON where possible and bounded DB mutation only where required, with approval, offline/maintenance safety, read-after-write confirmation, and rollback evidence.
 - `scum-workflow-automation`: Sequential workflow execution for SCUM operations, including workflow definitions, queueing, dependencies, status, retries, blocking states, and audit-safe progress reporting.
 - `scum-product-surface`: User management, squad management, realtime map, vehicle/flag management, gift management, AI assistant integration, and removal of raw log/terminal/config/history product surfaces.
 ### Modified Capabilities
 - None.
 ## Impact
 - `platform/`: domain models, repositories, services, validators, DTOs, API routes, run job projection, game player/gift/state services, audit-safe workflow records, and tests.
 - `platform_web/`: server detail route composition, SCUM plugin host contracts, first-party pages, API clients/types, AI assistant UI, and removal of raw product panels.
 - `plugins/`: SCUM plugin manifest, schemas, query templates, operation templates, companion handlers, feature pages/contracts, SDK validation, manifest tests, and plugin validation tooling.
 - External run repository: must implement the machine-side execution half for declared SCUM.db read models and controlled write operations without re-adding a `run/` tree to this repository.
 - Security boundaries: browser never receives SQL text, host paths, DSNs, credentials, run sockets, or raw protected request text; failed observations never overwrite last-known-good projections.
@@ -0,0 +1,63 @@
 ## ADDED Requirements
 ### Requirement: Typed SCUM operation catalog
 The system SHALL expose SCUM write capabilities only as typed operation declarations with schemas, permissions, approval level, execution transport, safety rules, and confirmation rules.
 #### Scenario: Manual player attribute edit
 - **WHEN** an operator requests a player attribute/stat edit such as field `855`
 - **THEN** platform creates a typed operation request containing player identity, field key, before value, after value, reason, requester, safety window, and idempotency key rather than accepting raw SQL from the browser
 #### Scenario: Operation declaration missing
 - **WHEN** a plugin page, platform service, or AI assistant requests an operation type not declared by the SCUM plugin manifest and platform validator
 - **THEN** platform rejects the request before any run job or protected request is created
 ### Requirement: Prefer game commands over database writes
 The system SHALL route SCUM write operations through game-supported commands such as RCON whenever a safe command exists, and SHALL use database mutation only for fields without a declared command path.
 #### Scenario: Fame and currency update
 - **WHEN** a user requests player fame, normal currency, or gold changes
 - **THEN** platform dispatches typed RCON operations using declared command templates and confirmation reads rather than issuing direct SCUM.db update statements
 #### Scenario: No game command exists
 - **WHEN** a requested field is declared as database-only by the plugin operation catalog
 - **THEN** platform dispatches a bounded DB mutation job with the declared template, parameter schema, row limit, before-value guard, and confirmation query
 ### Requirement: Approval and permission gates
 The system SHALL require role permission, operation approval, and lease-fenced run execution for all state-changing SCUM operations.
 #### Scenario: Operator requests platform-admin operation
 - **WHEN** an operator without platform-admin role requests a platform-admin SCUM mutation
 - **THEN** platform stores no executable payload and returns a forbidden result
 #### Scenario: Approved operation is claimed by run
 - **WHEN** an approved operation creates a run job
 - **THEN** run receives the executable request only through a current lease and fencing token, and platform stores only redacted or typed audit-safe payloads
 ### Requirement: Safety windows for database mutation
 The system SHALL require database mutations to pass configured safety checks such as player offline, maintenance verified, current-value match, bounded affected rows, and backup/snapshot evidence.
 #### Scenario: Player is online
 - **WHEN** a database-only player state mutation is requested while the latest verified projection shows the player online or safety state unknown
 - **THEN** platform blocks dispatch and records the request as waiting for an offline/maintenance safety window
 #### Scenario: Current value changed
 - **WHEN** run attempts a DB mutation and the current DB value no longer matches the approved `before` value
 - **THEN** run reports a stale-write failure and platform keeps the operation unconfirmed
 ### Requirement: Read-after-write confirmation
 The system SHALL mark SCUM write operations successful only after run reports execution success and platform accepts a typed confirmation observation proving the requested values now exist.
 #### Scenario: Command queued but not confirmed
 - **WHEN** RCON or DB mutation dispatch succeeds but confirmation read is missing or mismatched
 - **THEN** platform marks the operation pending-confirmation, failed-confirmation, or unknown instead of successful
 #### Scenario: Confirmation succeeds
 - **WHEN** the confirmation read returns the expected typed values, row identity, checksum, and observedAt
 - **THEN** platform marks the operation confirmed, updates local projections, and records audit evidence
 ### Requirement: AI produces reviewable operations only
 The system SHALL allow AI assistant output to create reviewable typed configuration diffs or typed SCUM operation drafts, but SHALL NOT allow AI to execute RCON, SQL, or file writes directly.
 #### Scenario: AI suggests a player correction
 - **WHEN** AI suggests changing a player attribute, fame, currency, gift eligibility, or plugin configuration value
 - **THEN** platform presents a typed diff or operation draft for human review and approval before any run-side execution can occur
@@ -0,0 +1,67 @@
 ## ADDED Requirements
 ### Requirement: SCUM user management surface
 The system SHALL provide a SCUM user management surface backed by local projections from login logs and SCUM.db observations.
 #### Scenario: Player list renders real records
 - **WHEN** an operator opens SCUM user management
 - **THEN** the page lists real player records with source, identity, character name, profile ID, Steam/user ID when known, squad, balances, fame, coordinates, online/session status evidence, and last observation freshness
 #### Scenario: Player edit opens typed workflow
 - **WHEN** an operator edits fame, currency, gift eligibility, or declared player state fields
 - **THEN** the page creates a typed operation workflow for review/approval instead of editing projected values directly
 ### Requirement: Squad and flag management surface
 The system SHALL provide squad and flag management backed by real `squad`, `squad_member`, `user_profile`, `base_element`, and related SCUM observations where available.
 #### Scenario: Squad page shows roster and territory
 - **WHEN** an operator opens squad management
 - **THEN** the page shows squads, members, ranks, leader, linked flags, member/player projection freshness, and unknown fields without fabricated owners or coordinates
 #### Scenario: Flag page shows stale ownership
 - **WHEN** a flag observation is stale or owner data cannot be verified
 - **THEN** the page marks the flag stale or unknown and offers a refresh workflow rather than inventing owner data
 ### Requirement: Realtime map surface
 The system SHALL provide a realtime SCUM map surface where players, vehicles, flags, squads, and selected risk overlays use platform-local projections and freshness state.
 #### Scenario: Map renders current projections
 - **WHEN** map data is fresh enough for display
 - **THEN** the page overlays players, vehicles, flags, squad territory, last-observed timestamps, and source confidence from local projections
 #### Scenario: Map data is stale
 - **WHEN** the map has stale or missing projections
 - **THEN** the page shows stale status and refresh workflow controls without using sample points, fake routes, or placeholder coordinates
 ### Requirement: Gift management surface
 The system SHALL provide gift catalog, schedule, eligibility, approval, delivery, notification, confirmation, and claim-state management using typed workflows.
 #### Scenario: Scheduled gift becomes eligible
 - **WHEN** a daily, weekly, monthly, yearly, one-time, or multi-per-day gift rule becomes eligible for a player type or achievement condition
 - **THEN** platform creates a gift delivery workflow and marks the grant delivered only after typed run/companion result and confirmation succeed
 #### Scenario: Delivery result unknown
 - **WHEN** delivery dispatch succeeds but confirmation is missing or ambiguous
 - **THEN** platform marks the grant unknown or pending-confirmation and prevents duplicate delivery until reconciliation completes
 ### Requirement: AI assistant remains for typed configuration and workflows
 The system SHALL keep the AI assistant as a first-party helper for plugin setup, config diffing, and operation drafts while routing all proposed effects through reviewable typed diffs or workflows.
 #### Scenario: AI configures plugin settings
 - **WHEN** an operator asks AI to configure the SCUM plugin
 - **THEN** AI can propose changes only for plugin-declared config fields, platform validates the diff, and approved changes use the existing config approval/dispatch path
 #### Scenario: AI suggests operation workflow
 - **WHEN** AI suggests a player correction, gift rule, map refresh, squad audit, or vehicle audit
 - **THEN** platform creates a draft workflow request that requires human review before execution
 ### Requirement: Raw product surfaces removed
 The system SHALL remove product-facing raw log, management terminal/RCON input, arbitrary config workbench, and generic operation history pages and dedicated APIs from the server detail experience.
 #### Scenario: Server detail route list is built
 - **WHEN** platform_web builds server detail navigation and plugin workspace contracts
 - **THEN** it excludes raw logs, management terminal, arbitrary config editor, and generic operation-history views while preserving AI assistant, typed workflows, lifecycle status, internal log ingest, audit, and run channels
 #### Scenario: Raw endpoint is requested
 - **WHEN** a browser calls a removed product-layer raw logs, terminal, arbitrary config, or operation-history API
 - **THEN** platform returns not found or the new typed workflow/status API without exposing raw terminal, raw SQL, raw host paths, or raw config editing capability
@@ -0,0 +1,56 @@
 ## ADDED Requirements
 ### Requirement: Authentic player identity creation
 The system SHALL create and update SCUM player identity records only from authentic SCUM login/logout log observations and verified SCUM.db facts reported by the bound run/agent for the current server instance.
 #### Scenario: Login log creates player record
 - **WHEN** run ingests a plugin-declared SCUM `login_*.log` line for a server-bound Steam/user identifier and character name
 - **THEN** platform stores or updates the matching local game player, player session, source log metadata, observed time, and confidence without inventing missing profile fields
 #### Scenario: Logout log updates session
 - **WHEN** run ingests a matching logout observation for a known player session
 - **THEN** platform closes or marks the local session with the observed logout time while preserving historical login evidence
 ### Requirement: Bound SCUM.db read observations
 The system SHALL obtain player, squad, vehicle, flag, position, economy, and observation facts from SCUM.db through server-bound run/agent jobs that execute plugin-declared read templates against the current service machine.
 #### Scenario: Current service database is queried
 - **WHEN** a server instance has an active run binding with the declared SCUM SQLite read capability
 - **THEN** platform queues declared read observation jobs for that server instance, run executes them against the local SCUM.db, and platform receives typed rows without exposing host paths, DSNs, sockets, or SQL text to the browser
 #### Scenario: Database unavailable
 - **WHEN** the bound run reports SCUM.db missing, locked, schema-incompatible, or unavailable
 - **THEN** platform records the observation failure and marks affected projections stale without replacing existing values with generated or placeholder data
 ### Requirement: Local projection surfaces
 The system SHALL persist local projections for players, squads, squad members, vehicles, flags, current positions, and data observations before any product surface reads them.
 #### Scenario: Typed result updates projections
 - **WHEN** platform accepts a successful typed query result for a server/plugin/query binding
 - **THEN** it validates schema, checksum, row bounds, observed time, and server binding before upserting the corresponding projection records
 #### Scenario: Page reads projection only
 - **WHEN** platform_web or a plugin page renders SCUM users, squads, vehicles, flags, or map positions
 - **THEN** it reads platform-local projections and freshness metadata rather than directly querying run, SCUM.db, or sample data
 ### Requirement: Freshness and conflict handling
 The system SHALL keep observation sequence, checksum, observedAt, receivedAt, and fresh/stale state for every projected SCUM data category.
 #### Scenario: Older observation arrives after newer one
 - **WHEN** platform receives an observation whose sequence or observedAt is older than the current projection for the same source key
 - **THEN** platform rejects it for projection while keeping an audit-safe observation record
 #### Scenario: Query failure after successful projection
 - **WHEN** a later read observation fails after a prior successful projection exists
 - **THEN** platform keeps the last-known-good projection, records the failure, and exposes stale status to the UI
 ### Requirement: Unknown fields stay unknown
 The system SHALL represent missing or unverifiable SCUM fields as unknown, absent, or stale instead of deriving fake values from unrelated tables or timestamps.
 #### Scenario: Steam ID missing from SCUM.db row
 - **WHEN** a SCUM.db player row has a user_profile_id but no verified user_id/Steam identifier
 - **THEN** platform stores the profile identifier separately and marks the external player identifier unknown rather than treating user_profile_id as Steam ID
 #### Scenario: last_save_time is present
 - **WHEN** a prisoner row includes `last_save_time`
 - **THEN** platform may use it as data freshness evidence but SHALL NOT use it alone as online-state proof
@@ -0,0 +1,68 @@
 ## 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
@@ -0,0 +1,101 @@
 ## 1. Workflow A - Contracts and Safety Model
 - [ ] 1.1 Positive prompt: Build the shared SCUM real-data and controlled-operation contract so platform, platform_web, and plugins agree on real observation records, typed write operations, workflow instances, and confirmation states.
 - [ ] 1.2 Directional prompt: Update `platform/domain`, `platform/dto`, `platform/validator`, `plugins/sdk`, and manifest schemas using existing job, bridge, protected request, gift, and player-state patterns; verify with Go tests and plugin type/schema tests.
 - [ ] 1.3 Boundary prompt: Do not add a `run/` tree, raw SQL browser payloads, host paths, DSNs, sockets, credentials, billing, hosting sales, or unrelated SaaS marketplace behavior.
 - [ ] 1.4 Define domain/DTO types for SCUM observations, projection freshness, workflow instances, workflow steps, operation requests, mutation guards, confirmation results, and safe summaries.
 - [ ] 1.5 Extend validators to reject arbitrary SQL/RCON/terminal fields in browser/plugin payloads while accepting declared typed query and operation template keys.
 - [ ] 1.6 Add tests proving raw SQL, host paths, direct sockets, credentials, and undeclared operation keys are rejected before job creation.
 ## 2. Workflow B - Real SCUM Data Observations
 - [ ] 2.1 Positive prompt: Read real current-server SCUM facts from login logs and SCUM.db through the bound run/agent, then persist local projections without fake data.
 - [ ] 2.2 Directional prompt: Extend existing log ingest, game player services, remote adapter/query template plumbing, and job result projection in `platform/`; verify with unit tests around stale observations and schema validation.
 - [ ] 2.3 Boundary prompt: Do not query SCUM.db from platform_web, do not expose SQL text or machine paths, and do not overwrite last-known-good projections on failed observations.
 - [ ] 2.4 Add projection repositories for players, live states, squads, squad members, vehicles, flags, current positions, and observation metadata.
 - [ ] 2.5 Wire login/logout log parsing to player/session projection creation and update, preserving source evidence and unknown fields.
 - [ ] 2.6 Add typed SCUM.db read-result projection handlers for player profile/economy, squads, squad members, vehicles, flags, and positions.
 - [ ] 2.7 Add freshness/stale-state logic with sequence, observedAt, receivedAt, checksum, query key, and server/plugin binding validation.
 - [ ] 2.8 Add tests for older observation rejection, failed-query stale marking, user_profile_id vs Steam/user ID separation, and `last_save_time` freshness-only behavior.
 ## 3. Workflow C - SCUM Plugin Read Templates
 - [ ] 3.1 Positive prompt: Declare SCUM plugin read templates for users, squads, vehicles, flags, and coordinates using real SCUM.db tables and typed result schemas.
 - [ ] 3.2 Directional prompt: Update `plugins/examples/scum-server-plugin/manifest.json`, `schemas/bridge/queries`, plugin tests, and manifest validation while keeping query declarations safe and route-scoped.
 - [ ] 3.3 Boundary prompt: Do not copy scum_robot management-library fields as SCUM.db facts, do not infer missing fields, and do not let pages submit SQL text.
 - [ ] 3.4 Add query templates for player profile/economy/position using `user_profile`, `prisoner`, `prisoner_entity`, `entity`, `bank_account_registry`, and `bank_account_registry_currencies`.
 - [ ] 3.5 Add query templates for squads and members using `squad`, `squad_member`, and `user_profile`.
 - [ ] 3.6 Add query templates for vehicles using `vehicle_spawner` and `entity`, with unknown/fallback vehicle labels when mapping is absent.
 - [ ] 3.7 Add query templates for flags using `base_element`, `user_profile`, `squad_member`, and `squad` where available.
 - [ ] 3.8 Add schema and validation tests for row bounds, typed result shape, page/template binding, and route permissions.
 ## 4. Workflow D - Controlled RCON Operations
 - [ ] 4.1 Positive prompt: Support safe fame, normal currency, gold, player notification, and reward command workflows through typed RCON operations where SCUM supports commands.
 - [ ] 4.2 Directional prompt: Build on existing source RCON/protected RCON dispatch and game client bridge command approval paths; verify with service tests for approval, redaction, and confirmation status.
 - [ ] 4.3 Boundary prompt: Do not restore a product terminal or arbitrary RCON input box; do not mark queued commands as delivered or successful.
 - [ ] 4.4 Declare typed RCON operation templates for `player.fame.set`, `player.currency.normal.set`, `player.currency.gold.set`, `player.notify`, and command-backed reward delivery.
 - [ ] 4.5 Add platform services to create, approve, dispatch, and reconcile typed RCON operation requests with idempotency and audit references.
 - [ ] 4.6 Add read-after-write confirmation using follow-up SCUM.db observation queries or typed companion results.
 - [ ] 4.7 Add tests for permission denial, protected text redaction, command unknown state, confirmation failure, and duplicate prevention.
 ## 5. Workflow E - Controlled DB Mutations
 - [ ] 5.1 Positive prompt: Support database-only player state edits such as field `855` through typed mutation templates with maintenance/offline safety and readback confirmation.
 - [ ] 5.2 Directional prompt: Extend operation template schemas, platform operation services, and run job execution contracts without storing raw mutation SQL in browser-visible records; verify with stale-write and confirmation tests.
 - [ ] 5.3 Boundary prompt: Do not use DB mutation for fame/currency when RCON exists, do not write more than declared row bounds, and do not proceed without before-value guards.
 - [ ] 5.4 Add mutation template declarations for DB-only player fields with field key, table/identity mapping metadata, allowed range, safety level, confirmation query, and max affected rows.
 - [ ] 5.5 Add platform approval flow requiring current projection, `before` match, offline/maintenance window, backup/snapshot evidence, and platform-admin approval.
 - [ ] 5.6 Add run job result validation for affected rows, mutation checksum, confirmation rows, and unknown execution states.
 - [ ] 5.7 Add tests for online-player blocking, missing maintenance window, stale before-value, over-bound affected rows, and successful confirmation.
 ## 6. Workflow F - Sequential Workflow Engine
 - [ ] 6.1 Positive prompt: Create a SCUM workflow queue that can run real-data refreshes and controlled operations one by one with dependency tracking.
 - [ ] 6.2 Directional prompt: Add platform workflow domain/repo/service/API code near existing job/game-client/gift/player-state services; keep run execution delegated through existing job channels.
 - [ ] 6.3 Boundary prompt: Do not replace the generic run job scheduler, do not block control heartbeat/log/artifact channels, and do not expose protected payload text in workflow status.
 - [ ] 6.4 Implement workflow instance and step state transitions: draft, queued, running, waiting, blocked, confirming, confirmed, failed, unknown, cancelled.
 - [ ] 6.5 Implement per-server sequential dispatch for state-changing steps and bounded concurrency for read-only observation steps.
 - [ ] 6.6 Add workflow templates for bootstrap real data, player refresh, world refresh, player correction, gift delivery, territory audit, vehicle audit, AI assist, and product cleanup.
 - [ ] 6.7 Add idempotency, fencing, retry, confirmation-before-retry, and blocker-safe-summary behavior.
 - [ ] 6.8 Add tests for ordered execution, dependency blocking, run-unavailable blocking, retry without duplicate effects, and terminal status projection.
 ## 7. Workflow G - Product APIs and Projection Views
 - [ ] 7.1 Positive prompt: Expose safe SCUM APIs for projection-backed users, squads, vehicles, flags, map overlays, gifts, operations, workflows, and AI drafts.
 - [ ] 7.2 Directional prompt: Add `platform/api`, `platform/dto`, and service handlers following existing resource handler patterns; verify authorization tests and DTO round trips.
 - [ ] 7.3 Boundary prompt: Do not expose raw logs, terminal input, arbitrary config file editing, generic operation-history APIs, SQL text, DSNs, host paths, or raw protected request payloads.
 - [ ] 7.4 Add list/detail APIs for SCUM players, squads, squad members, vehicles, flags, current positions, map overlays, and observation freshness.
 - [ ] 7.5 Add workflow APIs for creating refresh/correction/gift/audit/AI workflows, listing workflow status, approving required steps, cancelling safe pending steps, and reading audit-safe summaries.
 - [ ] 7.6 Update or remove legacy product APIs for raw logs, management terminal, raw config workbench, and generic operation history.
 - [ ] 7.7 Add authorization tests for operator vs platform-admin actions and raw endpoint removal/denial.
 ## 8. Workflow H - SCUM Product Surfaces
 - [ ] 8.1 Positive prompt: Replace SCUM plugin pages with real projection-backed user management, squad management, realtime map, vehicle/flag management, gift management, workflow status, and AI assistant surfaces.
 - [ ] 8.2 Directional prompt: Update `platform_web` contracts and SCUM plugin feature pages while preserving the black mecha and crystal-moonlight theme system; run typecheck and frontend tests.
 - [ ] 8.3 Boundary prompt: Do not introduce generic SaaS cards, page-local fixed decoration spans, raw terminal/log/config/history panels, or fake map/sample data.
 - [ ] 8.4 Build user management UI showing identities, sessions, projection source, squad, fame, balances, coordinates, freshness, and typed edit workflow launchers.
 - [ ] 8.5 Build squad/flag UI showing rosters, ranks, leaders, flags, ownership confidence, stale state, and refresh/audit workflow controls.
 - [ ] 8.6 Build realtime map UI using local projections for players, vehicles, flags, squads, timestamps, stale status, and refresh controls.
 - [ ] 8.7 Build gift UI for catalog versions, schedules, eligibility, claims, delivery workflow status, confirmation, unknown-state reconciliation, and player notifications.
 - [ ] 8.8 Keep AI assistant UI for typed config diffs and workflow drafts, wired to approval flows rather than raw file editing.
 - [ ] 8.9 Remove raw logs, management terminal, raw config workbench, and operation history routes from server detail navigation and plugin workspace contracts.
 ## 9. Workflow I - Run Integration Contract
 - [ ] 9.1 Positive prompt: Define the browser-repo contract expected from the independent run repository for SCUM.db reads, RCON writes, DB mutations, confirmation reads, and log ingestion.
 - [ ] 9.2 Directional prompt: Document and test platform/plugin protocol expectations in this repo; keep executable run implementation for `git@git.npc0.com:admin343/run.git` outside this repository.
 - [ ] 9.3 Boundary prompt: Do not add run source code here, do not require deployment target/run endpoint at server creation time, and do not leak component auth keys or host paths.
 - [ ] 9.4 Add protocol DTOs or contract docs for read observation inputs/results, mutation inputs/results, confirmation payloads, schema probes, and safe errors.
 - [ ] 9.5 Add compatibility tests/mocks proving platform can process run-style read/mutation/RCON results without real run code in this repository.
 - [ ] 9.6 Document external run tasks needed to execute SCUM.db query templates and controlled mutation templates on the service machine.
 ## 10. Workflow J - Verification, Cleanup, Commit
 - [ ] 10.1 Positive prompt: Verify the full SCUM integration change with backend, frontend, plugin, structure, and OpenSpec checks before committing.
 - [ ] 10.2 Directional prompt: Run targeted tests during implementation and final commands: `(cd platform && go test ./...)`, `(cd platform_web && npm run typecheck && npm run test && npm run build)`, `(cd plugins && npm run typecheck && npm run test && npm run validate:manifest)`, `scripts/check-structure.sh`, and `openspec validate integrate-real-scum-ops-workflows --strict`.
 - [ ] 10.3 Boundary prompt: Do not mark tasks complete without verification evidence, do not stage unrelated worktree changes, and do not push if required verification or credentials fail.
 - [ ] 10.4 Sweep for forbidden raw SQL/RCON/terminal/config/history product surfaces and unsafe browser-visible fields.
 - [ ] 10.5 Update documentation or comments only where they clarify new contracts and workflow behavior.
 - [ ] 10.6 Stage only files changed for this task, commit on `main`, and push to the configured remote after verification succeeds.