chore: consolidate platform split checks

docs/ACTION_EFFECT_AUTOMATION_LAYER.md

@@ -0,0 +1,121 @@
+# Action, Effect, And Automation Layer
+
+GovOPlaN needs an automation layer because administrative processes will not be
+only linear screen flows. Workflows, schedules, imports, connectors, policies,
+and external events all need to request governed actions without bypassing the
+same safety rules that apply to human users.
+
+The first implementation should live in `govoplan-workflow` and core contracts.
+Create a separate `govoplan-automation` module only if action planning,
+schedulers, rule execution, or cross-module automation become too broad for
+workflow ownership.
+
+## Layer Purpose
+
+The automation layer should provide:
+
+- a typed action catalogue
+- a typed effect catalogue
+- consequence preview before execution
+- policy and permission checks
+- idempotent execution
+- audit and provenance records
+- retry, quarantine, and manual exception handling
+- system-actor execution without hiding responsibility
+
+Automation is not a shortcut around module boundaries. It is a governed caller
+of module capabilities.
+
+## Action Definition
+
+An `ActionDefinition` describes something a human or system actor can request.
+
+Recommended fields:
+
+- `action_key`
+- owning module
+- input schema
+- actor requirements and required scopes
+- required capabilities
+- policy checks
+- risk level
+- reversibility class: reversible, compensatable, corrective-only, or
+  irreversible
+- expected effects
+- idempotency key strategy
+- audit event names
+- preview provider
+
+Examples:
+
+- create a case from a form submission
+- assign a task
+- generate a document from a template
+- send a postbox message
+- send an email notification
+- append evidence to records
+- create a payment request
+- call an external connector
+
+## Effect Definition
+
+An `EffectDefinition` describes the expected and observed result of an action.
+
+Recommended fields:
+
+- `effect_key`
+- affected module and resource references
+- external system references where applicable
+- created, changed, deleted, sent, notified, locked, or retained markers
+- visibility and privacy classification
+- audit event references
+- rollback or compensation hints
+- operator-facing explanation
+
+Effects should be recorded even when execution fails partially. This makes
+manual recovery and audit review possible.
+
+## Execution Model
+
+The runner should execute an action plan as follows:
+
+1. Resolve actor context: human, delegated actor, or system actor.
+2. Validate input schema.
+3. Resolve required module capabilities.
+4. Run permission and policy checks.
+5. Generate a consequence preview.
+6. Reserve or verify the idempotency key.
+7. Execute the owning module capability.
+8. Record observed effects.
+9. Emit events and audit records.
+10. Mark the command complete, retryable, quarantined, or requiring manual
+    intervention.
+
+The runner must never advance workflow state past a required side effect unless
+the action definition explicitly allows asynchronous completion and the pending
+state is visible.
+
+## Failure States
+
+Automation should use explicit failure states:
+
+- `blocked`: policy, permission, missing capability, or invalid input prevents
+  execution.
+- `retryable`: transient transport, timeout, rate-limit, or lock conflict.
+- `quarantined`: unexpected response, schema mismatch, unsafe partial result,
+  or unknown external state.
+- `manual_required`: human decision or correction is needed.
+- `compensation_required`: a later action must correct an already observed
+  side effect.
+
+These states should be visible in workflow, task, and admin diagnostics.
+
+## Boundary
+
+Core may own stable DTOs, registry contracts, and generic audit/event hooks.
+`govoplan-workflow` should own the first runner because workflow is the first
+module that coordinates cross-module process actions.
+
+Domain modules own their own action providers. For example, templates own
+document generation actions, postbox owns postbox message actions, and
+connectors own external handoff actions.