issue-core/workplans/ISSUE-WP-0004-align-with-work-record-canon.md

---
id: ISSUE-WP-0004
type: workplan
title: "Align issue-core with the work-record canon (connector, not landing zone)"
domain: infotech
repo: issue-core
status: finished
owner: codex
topic_slug: infotech
created: "2026-07-20"
updated: "2026-07-21"
state_hub_workstream_id: "ee47385f-aadb-4dba-b39f-148ac1444c3d"
---

# Align issue-core with the work-record canon (connector, not landing zone)

## Origin

The-custodian's `canon/standards/work-record-types_v0.1.md` (ratified
2026-07-20, `CUST-WP-0060`) and its architecture draft
(`research/WorkOrchestrationArchitectureDraft.md` v0.2, founder-reviewed
2026-07-20, §4.2) settled issue-core's fleet role — a decision made *while
reviewing a live incident this repo caused*: `activity-core`'s
`daily-todo-md-stale-review` ActivityDefinition routed its findings through
`IssueSink` → issue-core → Forgejo, producing 5 issues nobody was meant to
see (Forgejo issue tracking is not the fleet coordination mechanism). That
activity is now paused pending a proper fix (`the-custodian`
technical-debt-adjacent follow-up in `CUST-WP-0060`'s closure review, item 6).

**issue-core's current `INTENT.md` directly contradicts the agreed role.**
It states: *"The Coulomb org needs a single, observable place where tasks
land — regardless of whether they were created by a human ... an automation
like activity-core ... or by an agent."* That is precisely the
landing-zone role the fleet decided issue-core should **not** hold — work
records originate as repo files per ADR-001; issue-core was never meant to
be an alternative origin.

**Founder-reviewed decision (verbatim, `WorkOrchestrationArchitectureDraft.md`
§4.2, "issue-core: third-party connector, not core loop"):**

> issue-core's role is a **connector framework to external issue-tracking
> systems** (Forgejo issues, Jira, GitHub, …): it maintains the mapping
> between internal work-record UUIDs and external issue ids and provides
> two-way, transclusion-like sync *at the boundary* when we collaborate
> through a third-party tracker. It is not part of the internal execution
> loop — claiming and execution run on work records directly (harness
> intake via NATS/activity-core per its stated target). Until an external
> integration is actually switched on, the connector layer adds zero load.

This workplan brings issue-core's own docs, scope, and (where cheap) code
in line with that decision. It does not remove issue-core's existing
capability — Gitea/GitHub backend CRUD stays useful — it retargets *what
issue-core is for*.

## Task: Rewrite INTENT.md — connector, not landing zone

Replace the "single, observable place where tasks land" framing with the
connector framing above. Keep the honest history (it *was* built as a
landing zone; note the pivot and why, dated). Update the "What it is NOT"
section to explicitly add: *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`) — issue-core provides the
external-tracker projection when one is in use.* Green lane (docs only).

```task
id: ISSUE-WP-0004-T01
status: done
priority: high
state_hub_task_id: "ae1e2a1e-8127-46bb-b7d7-be5c647f61ef"
```

**Done 2026-07-21:** `INTENT.md` rewritten with connector framing, dated
pivot, and expanded "What it is NOT".

## Task: Rewrite SCOPE.md — mapping table, not ingestion primary path

Current SCOPE.md lists activity-core's `POST /issues/` `TaskSpec` path as
"Primary integration." Reframe: CLI/REST ingestion stays for direct
human/backend use, but the *primary* fleet path is no longer "automation
emits a task into issue-core" — it is "a work record exists in a repo
file; issue-core optionally projects it to an external tracker and tracks
the UUID ↔ external-id mapping." Add an explicit mapping-table concept to
scope (internal work-record UUID ↔ backend issue id), even if not yet
implemented — name the target shape before building it. Green lane.

```task
id: ISSUE-WP-0004-T02
status: done
priority: high
state_hub_task_id: "cd0422f6-6921-4ac6-a484-19b6777d99bc"
```

**Done 2026-07-21:** `SCOPE.md` reframed; mapping table concept named;
TaskSpec retained as optional intentional path.

## Task: Audit and update README / ROADMAP for the same framing

`README.md`'s "Why Issue Tracking for Agent Coordination?" section and
`ROADMAP.md`'s feature trajectory both currently assume issue-core is the
coordination substrate. Update both to point at the work-record canon as
the coordination substrate and issue-core as its optional external-tracker
bridge. Cross-link `the-custodian/canon/standards/work-record-types_v0.1.md`
and the architecture draft. Green lane.

```task
id: ISSUE-WP-0004-T03
status: done
priority: medium
state_hub_task_id: "746d090d-ebed-4328-bcd8-d531706ae795"
```

**Done 2026-07-21:** README + ROADMAP updated; Phase 0 + Phase 1.5 mapping
called out.

## Task: Design the UUID ↔ external-id mapping surface (design only)

Specify (not implement) how issue-core will record the internal work-record
UUID alongside the backend issue id it creates, so a future
`kind: intake` (or any) work record can carry a
`state_hub_*_id`-style back-reference to its external-tracker projection —
mirroring the pattern already used for workplan/task UUIDs. Note where this
intersects `TaskSpec.triggering_event_id` (currently the only
traceability field) and whether it should be superseded or extended.
Output: a design note in `docs/`, no code yet — implementation is stage-3
scope in the-custodian's work-record architecture, not this workplan.
Green lane.

```task
id: ISSUE-WP-0004-T04
status: done
priority: medium
state_hub_task_id: "61ba9b84-a2cc-4b20-b8d3-9fc8487f7acf"
```

**Done 2026-07-21:** `docs/uuid-external-id-mapping.md` — extend
`triggering_event_id`, add `work_record_uuid` + mapping rows; no code.

## Task: Fix activity-core's IssueSink call site to match

`activity-core`'s `issue_sink.py` (`IssueCoreRestSink`) currently treats
`POST /issues/` as the default, always-on path for any matched rule
(`ISSUE_SINK_TYPE=rest` is the deployment default). Once T01–T03 land here,
open the corresponding activity-core-side task: the default sink should not
silently create Forgejo issues for internal findings. Cross-repo — this
task in issue-core is to **file that follow-up** (workplan or task in
activity-core, referencing this workplan and `CUST-WP-0060` item 6), not to
implement the activity-core change itself. Green lane.

```task
id: ISSUE-WP-0004-T05
status: done
priority: medium
state_hub_task_id: "944e0510-42c3-48f3-a7d2-86853468f816"
```

**Done 2026-07-21:** Filed
`activity-core/workplans/ACTIVITY-WP-0022-issuesink-no-default-forgejo.md`
(`status: proposed`) with tasks for default sink policy, implementation,
definition reroute, and deploy docs. Cross-links ISSUE-WP-0004 and
CUST-WP-0060 item 6. Implementation remains in activity-core.