issue-core/INTENT.md

# 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).