docs: add SCOPE.md for rapid orientation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SCOPE.md

@@ -0,0 +1,94 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+Event-driven task factory backbone using Temporal — defines ActivityDefinitions that spawn TaskInstances when triggered by cron schedules or domain events, with durable execution and PostgreSQL persistence.
+
+---
+
+## Core Idea
+
+Activity-core replaces ad-hoc cron jobs and Celery tasks with a durable Temporal-based workflow engine. An `ActivityDefinition` declares what triggers it (cron or event), how to resolve context, and what task templates to spawn. When triggered, a `RunActivityWorkflow` executes durably, creating `TaskInstance` records and run logs. Server crashes replay automatically from Temporal's event log.
+
+---
+
+## In Scope
+
+- Domain model: ActivityDefinition, EventEnvelope, CronTriggerConfig, EventTriggerConfig, RunActivityWorkflow, TaskInstance
+- Trigger types: 5-field cron (with timezone, jitter, misfire policy) or event-based (EventEnvelope type + payload filters)
+- EventEnvelope normalization: standard internal event format for all inbound events
+- Context resolution: load definition from DB, resolve context sources, evaluate rules
+- Task spawning: generate TaskInstance records as child workflows/activities
+- Run logging: audit trail of activity executions, task creation, completion
+
+---
+
+## Out of Scope
+
+- Temporal server hosting/operations (activity-core consumes Temporal SDK; infra is separate)
+- End-user task UI (TaskInstance records are created; presentation is a separate concern)
+- Event broker integration (upstream router delivers EventEnvelopes; activity-core receives them)
+- Synchronous request-response workflows (Temporal is async-first)
+
+---
+
+## Relevant When
+
+- Need durable, time-triggered or event-triggered task generation with crash resilience
+- Want an audit trail of activity runs and spawned task instances
+- Replacing unreliable cron + Celery patterns with replay-safe Temporal workflows
+
+---
+
+## Not Relevant When
+
+- Simple system cron jobs with no durability requirement
+- Synchronous request-response patterns
+- Existing Celery infrastructure is working (migration is non-trivial)
+
+---
+
+## Current State
+
+- Status: concept → planning (pre-alpha)
+- Implementation: ~30% — domain model defined (EventEnvelope, ActivityDefinition, trigger configs); PostgreSQL schema planned; Temporal workflows.py + activities.py not yet scaffolded
+- Stability: unstable — models are valid but untested in real workflows
+- Usage: none yet; proto-planning phase
+
+---
+
+## How It Fits
+
+- Upstream dependencies: Temporal (orchestration engine), PostgreSQL (persistence), ops-bridge (network tunnel to remote Temporal server)
+- Downstream consumers: Custodian State Hub tracks activity-core workstreams; tasks spawned feed into other systems
+- Often used with: kaizen-agentic (project scaffolding), the-custodian (workstream tracking), railiance (Temporal server may run on Railiance infrastructure)
+
+---
+
+## Terminology
+
+- Preferred terms: ActivityDefinition, EventEnvelope, RunActivityWorkflow, TaskInstance, trigger, misfire policy
+- Also known as: "the task factory", "activity backbone"
+- Potentially confusing terms: "Activity" is a Temporal concept (a single executable step); "ActivityDefinition" is the app-level record that configures what gets spawned
+
+---
+
+## Related / Overlapping Repositories
+
+- `the-custodian` — tracks activity-core workstreams in State Hub (domain: custodian)
+- `ops-bridge` — provides network tunnel to remote Temporal server
+- `railiance-cluster` / `railiance-platform` — may host Temporal server
+
+---
+
+## Getting Oriented
+
+- Start with: `CLAUDE.md` (session protocol, repo boundary), `wiki/ActivityCorePlan_chtgpt.md` (proto-architecture)
+- Key files / directories: `src/activity_core/models.py` (EventEnvelope, ActivityDefinition), `workplans/` (roadmap), `docker-compose.dev.yml` (local Temporal + PostgreSQL)
+- Entry points: models.py is the current starting point; workflows.py does not yet exist