# INTENT — issue-core ## Why it exists The Coulomb org collaborates through **external issue trackers** (Forgejo / Gitea, GitHub, Jira, …) when a human counterparty, open-source workflow, or third-party process requires it. Those systems are not the fleet's internal coordination substrate — that role belongs to **work records** authored as repo files (ADR-001) and indexed by state-hub. issue-core exists so that, **when an external tracker is actually in use**, every actor can project, query, and update issues through one backend-agnostic interface — and so the fleet can keep a stable **mapping** between internal work-record identity (UUIDs) and external issue ids. Without a connector layer, external-tracker access fragments across: - Per-repo Gitea / Forgejo API clients (siloed, no shared mapping) - Ad hoc `gh` / `glab` / curl scripts (untyped, unaudited) - Agent-local integrations (lost when the agent ends) - Direct SaaS API calls (rate-limited, off-network, no UUID back-reference) issue-core gives humans and machines one stable surface to talk to external trackers, and (target shape) one place that records which internal work record projects to which external issue. ## Honest history (pivot, 2026-07-20) issue-core was originally built and documented as a **task landing zone**: a single observable place where humans, activity-core, and agents filed work via CLI / REST / future NATS, with Gitea as the default store. That framing contradicted the fleet decision that work originates as **repo files** and that Forgejo issues are not the coordination mechanism. The pivot was ratified while reviewing a live incident: activity-core's `daily-todo-md-stale-review` ActivityDefinition routed findings through `IssueSink` → issue-core → Forgejo, producing issues nobody was meant to see as fleet work. Founder-reviewed architecture draft §4.2 (`the-custodian/research/WorkOrchestrationArchitectureDraft.md` v0.2, 2026-07-20) and the work-record canon (`the-custodian/canon/standards/work-record-types_v0.1.md`, CUST-WP-0060) settled the role below. Capability (CRUD, backends, REST, sync) stays; the *purpose* is retargeted to connector, not origin. ## What it is A **connector framework to external issue-tracking systems**, with a pluggable-backend architecture. Responsibilities: - **Projection / CRUD**: create, read, update, close, and comment on issues in the configured backend (Gitea/Forgejo, SQLite offline cache, planned GitHub / GitLab / Jira). - **Mapping (target)**: maintain internal work-record UUID ↔ external issue id so a work record can carry a back-reference to its tracker projection (design: `docs/uuid-external-id-mapping.md`). - **Boundary sync**: two-way, transclusion-like sync *at the boundary* when collaboration runs through a third-party tracker — not as the internal execution loop. - **CLI + REST**: human and automation surfaces for direct backend use when a tracker is intentionally switched on. - **Optional ingestion**: `POST /issues/` remains for authenticated clients that deliberately create tracker issues; it is **not** the primary fleet path for internal findings or work origin. Backends today: **local SQLite**, **Gitea**. Planned: **GitHub**, **GitLab**, **JIRA**. The CLI entry points are `issue` (primary) and `issue-core` (explicit alias). Until an external integration is actually switched on for a given workflow, the connector layer should add **zero load** to the internal coordination loop. ## What it is NOT issue-core is intentionally narrow. The following live elsewhere: - **Not the origin of work records.** Work records originate as repo files per ADR-001 (`the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md` and the work-record types standard). issue-core provides the **external-tracker projection** when one is in use. Internal tasks, intake items, workplans, and decisions are not created here. - **Not the internal execution / coordination loop.** Claiming and execution run on work records directly (harness intake via NATS/activity-core per its stated target). Fleet orientation is state-hub + repo files, not Forgejo issue lists. - **Not a project manager.** Phases, campaigns, milestones spanning multiple tasks, dependency graphs across tasks, gantt-style scheduling — that is the domain of workplans / project tooling. issue-core deals in individual external issues, not in plans composed of tasks. - **Not a spawn audit trail.** When an upstream service deliberately emits an issue here, the *spawn event* belongs to the emitter (e.g. activity-core's `task_spawn_log`). issue-core stores the resulting issue and optional traceability fields (`triggering_event_id`, future work-record UUID) — not the audit-of-creation. - **Not an event bus.** Communication between services flows over NATS (and state-hub progress events). issue-core consumes or serves specific boundaries; it does not relay events between other services. - **Not a notification system.** Surfacing "your task changed" to humans is the job of the relevant UI / digest / chatbot layer, not issue-core. - **Not a workflow engine.** State transitions are simple (open → closed, with a few in-between states). Conditional routing, approvals, multi-step workflows — out of scope. ## How it fits ``` Work records (repo files, ADR-001) External collaboration ───────────────────────────────── ────────────────────── workplan / task / intake / … Counterparty, OSS, Jira, … │ │ │ optional project when │ │ a tracker is switched on │ v v +------------------+ UUID ↔ issue id +------------------+ | state-hub | <---- mapping ------> | issue-core | | (read model) | | (connector) | +------------------+ +--------+---------+ | +---------+----------+ | Backend router | +---+------+------+--+ | | | v v v +------+ +-----+ +------+ |Gitea | |SQLite| |GitHub| |Forgejo| |cache| | … | +------+ +-----+ +------+ Direct use (human CLI / intentional REST) still goes to issue-core without creating a work-record origin — useful for tracker admin and collaboration, not for fleet task birth. ``` **Primary fleet path (coordination):** 1. A work record exists in a repo file (or is registered from one). 2. Humans/agents claim and execute against that record (and state-hub views). 3. **Optionally**, issue-core projects the record to an external tracker and records the UUID ↔ external-id mapping. **Secondary path (direct tracker use):** - **Humans** — `$ issue create ...` when deliberately working in a backend. - **Authenticated automation** — `POST /issues/` only when the product decision is "create an external issue," not "spawn fleet work." - **activity-core IssueSink** — must not be the default always-on path for internal findings (see ISSUE-WP-0004-T05 / activity-core follow-up). **Downstream:** - Backend native UIs (Gitea web, GitHub, …) for external collaboration. - state-hub for fleet lifecycle visibility of *work records*, not of every issue-core row. ## Success looks like - External trackers are usable through one CLI/API without each agent learning platform-specific clients. - When a work record is projected outward, the UUID ↔ external-id mapping is durable and inspectable (once implemented per the design note). - Internal automation does **not** silently open Forgejo issues for findings that belong in repo work records. - Offline SQLite work syncs cleanly to a remote backend when connectivity returns. - With no external integration switched on, issue-core adds no load to the internal loop. ## See also - `SCOPE.md` — concrete in/out-of-scope decisions and integration boundaries. - `ROADMAP.md` — feature trajectory (connector-aligned). - `docs/uuid-external-id-mapping.md` — design for the mapping surface. - `workplans/ISSUE-WP-0004-align-with-work-record-canon.md` — this pivot. - `the-custodian/canon/standards/work-record-types_v0.1.md` — work-record canon. - `the-custodian/research/WorkOrchestrationArchitectureDraft.md` §4.2 — founder-reviewed connector role. - activity-core `docs/adr/adr-001-event-bridge-architecture.md` — IssueSink contract at `POST /issues/` (optional, intentional use only).