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