diff --git a/workplans/ISSUE-WP-0004-align-with-work-record-canon.md b/workplans/ISSUE-WP-0004-align-with-work-record-canon.md new file mode 100644 index 0000000..ce98469 --- /dev/null +++ b/workplans/ISSUE-WP-0004-align-with-work-record-canon.md @@ -0,0 +1,136 @@ +--- +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: ready +owner: codex +topic_slug: infotech +created: "2026-07-20" +updated: "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). + +```task +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. + +```task +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. + +```task +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. + +```task +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. + +```task +id: ISSUE-WP-0004-T05 +status: todo +priority: medium +```