issue-core/SCOPE.md

SCOPE — issue-core

Concrete in-scope / out-of-scope decisions for issue-core. Paired with INTENT.md, which explains why; this file states what and what not.

In scope

Task CRUD across backends

• Create issues with title, description, labels, priority, type, milestone, assignee, due date.
• Read individual issues and lists with filters (state, labels, priority, assignee, text search).
• Update any mutable field on existing issues.
• Close / reopen with state transitions enforced at the domain layer.
• Delete where the backend allows (local SQLite; soft-archive elsewhere).
• Comment threads on issues.

Backend abstraction

• A single IssueBackend ABC contract that every backend implements.
• BackendCapabilities declares which optional features a backend supports (bulk update, search, milestones, etc.).
• A BackendFactory registry that maps config to backend instances.

Backends shipped today

• Local SQLite — offline source of truth.
• Gitea — REST API integration.

Backends planned

• GitHub — Issues + PRs.
• GitLab — Issues.
• JIRA — issues with story-points.

Ingestion surfaces

• CLI (issue / issue-core) for humans and agents on a shell.
• REST (POST /issues/) for automation — primarily activity-core's IssueSink, but open to any well-authenticated client.
• NATS subscriber (design stub only — implementation deferred until activity-core migrates from REST to NATS, see docs/nats-task-ingestion.md).

Synchronization

• Local SQLite ↔ remote backends, bidirectional.
• get_issues_modified_since() on SyncableBackend for incremental sync.
• Conflict resolution via SyncableBackend.resolve_sync_conflict().
• Sync metadata (last-synced timestamps, remote IDs) stored on Issue.sync_metadata.

State Hub integration

• Registered as a custodian-domain repo.
• Emits add_progress_event() calls on significant task lifecycle moments.
• Surfaces blocked tasks via the hub's list_blocked_tasks() view.

Out of scope

Project management

Phases, campaigns, milestones-as-plans, dependency graphs between tasks, gantt-style scheduling, OKR linkage. That is project-core (planned). issue-core operates on individual tasks. A milestone field exists for flat grouping, not for multi-stage plans.

Spawn audit trail

When activity-core's IssueSink files a task here, the spawn event (who fired the rule, against which activity definition, on which triggering event) is recorded in activity-core's task_spawn_log. issue-core stores the resulting task and a back-reference (triggering_event_id) — nothing more.

Symmetrically: issue-core does not push status updates back to activity-core. Lifecycle updates stay here; activity-core does not care what happens to a task it spawned.

Event bus / message broker

Inter-service communication runs on NATS managed elsewhere. issue-core consumes specific subjects (future) and exposes a REST surface; it does not relay events between other services.

Notifications

Telling a human "your task changed" is the job of the relevant UI, digest, chatbot, or notification service — not issue-core. issue-core emits progress events; downstream consumers decide what to do with them.

Workflow / approval engine

State machine is intentionally small (OPEN, CLOSED, IN_PROGRESS, BLOCKED). Conditional routing, approval chains, multi-step workflows, SLA timers — all out of scope.

UI

issue-core is CLI + REST first. Each backend brings its own native UI (Gitea web, GitHub web, etc.) and that is enough. A web UI for issue-core itself is not on the roadmap.

Identity / access management

Authentication relies on backend credentials (Gitea tokens, GitHub tokens) and on a service-level API key for the REST ingestion endpoint. issue-core is not a user directory.

Integration boundaries

Upstream emitters

Emitter	Transport	Payload	Notes
Human CLI	local process call	CLI args	The classic path.
activity-core	REST POST /issues/	TaskSpec (see below)	Primary integration; planned NATS migration.
Agents	REST or CLI	TaskSpec or CLI args	Same surfaces as humans/automation.

Downstream consumers

Consumer	Mechanism	Notes
Humans / agents	issue list, web UI, backend UI	Standard task pickup.
state-hub	add_progress_event() calls	Lifecycle visibility.
Backend remote (e.g. Gitea)	direct backend write	Pass-through for the storage layer.

TaskSpec payload (from activity-core's IssueSink)

{
  "title": "string",
  "description": "string",
  "target_repo": "string",
  "priority": "high | medium | low",
  "labels": ["string"],
  "due_in_days": 7,
  "source_type": "rule | instruction",
  "source_id": "string",
  "triggering_event_id": "uuid",
  "activity_definition_id": "string"
}

POST /issues/ response

{
  "issue_id": "string",
  "issue_url": "string or null",
  "backend": "gitea | sqlite | github"
}

The issue_id is the canonical back-reference activity-core stores in its task_spawn_log. It is owned and managed by issue-core; activity-core does not mutate it.

See also

• INTENT.md — why issue-core exists and how it fits in the Coulomb org.
• ROADMAP.md — feature trajectory.
• workplans/ISSC-WP-0001-rename-and-task-ingestion.md — current rename + ingestion workstream.
• activity-core docs/adr/adr-001-event-bridge-architecture.md — the upstream side of the IssueSink contract.