issue-core/INTENT.md

INTENT — issue-core

Why it exists

The Coulomb org coordinates work through work records: identified, lifecycle-bearing artefacts authored as repo files (ADR-001), indexed by state-hub, under a closed kind registry (workplan, task, intake, decision, engagement, register-entry). That framework is defined in the-custodian/canon/standards/work-record-types_v0.1.md and the founder- reviewed architecture draft (WorkOrchestrationArchitectureDraft.md v0.2).

External issue trackers (Forgejo / Gitea, GitHub, Jira, …) remain necessary when a human counterparty, open-source workflow, or third-party process lives there. They are not the fleet coordination substrate and are not a work-record kind. Canon is explicit: issue-core issues become external projections only.

issue-core exists so that, when an external tracker is actually in use, the fleet has one backend-agnostic surface to project, query, and update tracker issues — and (target) a durable mapping between:

Side	Identity
Internal work record	UUIDv7 (bookkeeping / mapping key) + canonical name for humans and agents (ISSUE-WP-0005-T01, …)
External issue	(backend, external_id) (+ URL)

Without a connector layer, external-tracker access fragments across per-repo API clients, ad hoc gh/glab/curl, agent-local integrations, and SaaS calls with no stable back-reference to the work record.

Honest history (pivot, 2026-07-20)

issue-core was originally built and documented as a task landing zone: a single place where humans, activity-core, and agents filed work via CLI / REST, with Gitea as the default store. That framing contradicted file-first work records and produced a live incident (daily-todo-md-stale-review → IssueSink → Forgejo issues that were never fleet work).

Architecture draft §4.2 and the work-record types standard (CUST-WP-0060) retargeted purpose: connector, not origin. Capability (CRUD, backends, REST, backend-to-backend sync) stays; product north star is projection and mapping at the boundary.

What it is

A connector framework to external issue-tracking systems, with a pluggable-backend architecture. Issue-core is not part of the internal execution loop.

Shipped today

• Tracker CRUD on configured backends: create, read, update, close / reopen, comment (and related label / assignee / milestone operations).
• Backends: local SQLite (offline store / cache), Gitea (Forgejo- compatible in deployment). Further backends (GitHub, GitLab, Jira) are product growth, not yet implemented.
• CLI (issue / issue-core) and Python library for direct backend use.
• REST (issue serve, optional [api] extra): intentional create (POST /issues/), list/get/claim (GET/PATCH /issues/).
• Backend↔backend sync via CLI (e.g. Gitea ↔ SQLite) — not the same as work-record boundary sync below.
• Optional intentional ingestion of TaskSpec payloads for clients that deliberately create tracker issues (not the fleet path for internal findings).

Target connector (stage-3 work-record architecture)

• Mapping store: durable work-record UUIDv7 ↔ (backend, external_id), resolvable also by canonical work-record id; design in docs/uuid-external-id-mapping.md.
• Project / link CLI and API: project an existing work record outward, or link an existing external issue; idempotent on active mapping.
• Boundary sync (when enabled): optional two-way, transclusion-like sync at the boundary for fields needed by external collab. Zero load when no mapping/integration is configured.
• Extend TaskSpec with optional work_record_uuid (and kind/id denorm); do not overload triggering_event_id (activity lineage only).
• Optional work-record file back-reference (canon-owned field names), mirroring hub state_hub_*_id write-back patterns.

Until an external integration is switched on for a given workflow, the connector must add no coordination load to the internal loop.

What it is NOT

• Not the origin of work records. Work records originate as repo files (or schema-valid blocks in context) per ADR-001 and the work-record types standard. issue-core does not create workplans, tasks, intake items, decisions, engagements, or register entries as fleet artefacts.

• Not a work-record kind. Tracker issues are not registered in work-record-types. Unmapped backend issues sit outside the work-record spine; they are external artefacts for tracker UI collaboration until mapped to a work-record UUID.

• Not the internal execution / coordination loop. Humans and agents claim and execute on work records (harness / NATS / activity-core as feeds). Fleet orientation is state-hub views over indexed files — not Forgejo issue lists. (Avoid calling this “intake” when you mean claim/execute; intake is a work-record kind for sparks/findings.)

• Not the default home for automation findings. Internal findings belong as kind: intake (then promotion to task / workplan / decision / engagement). They must not silently become Forgejo issues via IssueSink. Emitter policy: activity-core ACTIVITY-WP-0022 (from ISSUE-WP-0004-T05 / CUST-WP-0060).

• Not a second autonomy or budget model. lane, tags, and budgets live on the work record. Projections carry only what external collab needs (title, body, agreed labels); they must not invent parallel lane/budget semantics on Gitea labels without explicit rules.

• Not a project manager, spawn audit trail, event bus, notification system, or workflow engine. Plans and dependencies are workplan tooling; spawn audit stays with emitters; NATS/hub own inter-service events; notifications and approval chains live elsewhere. Tracker state machine stays small (open / in_progress / blocked / closed).

Boundary sync discipline

Fleet work-record status (e.g. task wait → todo → progress → done | cancel) and tracker IssueState (open / in_progress / blocked / closed) are distinct vocabularies. They must not be merged casually.

• Outward / inward projection uses explicit mapping rules.
• Inward changes never silently mutate ADR-001 work-record files without a defined writer (see mapping design open questions).
• Backend↔backend CLI sync is orthogonal to work-record boundary sync.

How it fits

  Repo files (ADR-001 / work-record kinds)     External collaboration
  workplan · task · intake · decision ·        Counterparty, OSS, Jira, …
  engagement · register-entry
           │
           │ fix-consistency: register, UUIDv7 write-back
           v
  +------------------+
  |  state-hub       |   read model + generated views  (not mapping authority)
  +------------------+
           │
           │ optional project / link when a tracker is switched on
           v
  +------------------+     UUIDv7 (+ canonical id)     +------------------+
  |  work-record     | <---- mapping (target) ------> |  issue-core      |
  |  source (+ opt.  |     ↔ (backend, external_id)   |  (connector)     |
  |  back-ref)       |                                 +--------+---------+
  +------------------+                                          |
                                                      +---------+----------+
                                                      |  Backend router    |
                                                      +---+------+------+--+
                                                          |      |      |
                                                          v      v      v
                                                     Gitea/  SQLite  GitHub
                                                     Forgejo  cache   (planned)

Primary fleet path (coordination):

1. Author or promote a work record in a repo file (kind from the closed registry; findings enter as intake, then promote).
2. fix-consistency indexes the record and write-backs UUIDv7.
3. Claim / execute against the work record (and hub views).
4. Optionally, issue-core projects or links the record to an external tracker and records the mapping (target).

Secondary path (direct tracker use):

• Humans/agents use CLI/REST when deliberately operating on a backend (tracker admin, pure external collab).
• Authenticated POST /issues/ only when the product decision is “create an external issue,” not “spawn fleet work.”
• Unmapped issues remain outside the work-record spine.

Downstream:

• Backend native UIs for external collaboration.
• state-hub for fleet lifecycle of work records, not of every issue-core row.

Success looks like

• External trackers usable through one CLI/API without per-platform clients.
• When a work record is projected, UUIDv7 ↔ external-id mapping is durable and resolvable by canonical name (once implemented).
• Fleet status and tracker state stay cleanly separated under explicit rules.
• Internal automation does not open Forgejo issues for findings that belong as intake / promoted work records.
• Unmapped tracker issues are not mistaken for fleet work records.
• With no integration switched on, the connector adds no load to the internal loop.
• Offline SQLite backend sync still works for tracker data when connectivity returns.

See also

• SCOPE.md — shipped inventory, product boundary, TaskSpec contract.
• docs/uuid-external-id-mapping.md — mapping design (not implemented).
• docs/intent-work-record-alignment-review.md — audit that drove this rewrite.
• workplans/ISSUE-WP-0004-align-with-work-record-canon.md — initial pivot.
• workplans/ISSUE-WP-0005-connector-alignment-implementation.md — close shipped-scope gaps against this intent.
• the-custodian/canon/standards/work-record-types_v0.1.md — kind registry, spine, identity, promotion.
• the-custodian/research/WorkOrchestrationArchitectureDraft.md §4.2 — connector decision.
• the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md.
• activity-core ACTIVITY-WP-0022 — IssueSink default policy (emitter side).