tegwick d60175c354

CI Smoke / host-smoke (push) Successful in 0s

Details

CI Smoke / container-smoke (push) Successful in 2s

Details

docs: align issue-core with work-record connector role (ISSUE-WP-0004)

Retarget INTENT, SCOPE, README, ROADMAP, and agent docs from "task landing
zone" to external-tracker connector per work-record canon and architecture
draft §4.2. Add UUID↔external-id mapping design; mark ISSUE-WP-0004 finished
and cross-file activity-core ACTIVITY-WP-0022 for IssueSink policy.

2026-07-21 04:22:12 +02:00

9 KiB

Raw Blame History

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):

A work record exists in a repo file (or is registered from one).
Humans/agents claim and execute against that record (and state-hub views).
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.

9 KiB Raw Blame History