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

id	type	title	domain	repo	status	owner	topic_slug	created	updated
ISSUE-WP-0004	workplan	Align issue-core with the work-record canon (connector, not landing zone)	infotech	issue-core	ready	codex	infotech	2026-07-20	2026-07-20

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

id: ISSUE-WP-0004-T01
status: todo
priority: high

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.

id: ISSUE-WP-0004-T02
status: todo
priority: high

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.

id: ISSUE-WP-0004-T03
status: todo
priority: medium

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.

id: ISSUE-WP-0004-T04
status: todo
priority: medium

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.

id: ISSUE-WP-0004-T05
status: todo
priority: medium