issue-core/workplans/ISSUE-WP-0005-connector-alignment-implementation.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
ISSUE-WP-0005	workplan	Implement connector alignment: mapping, docs hygiene, scope gaps vs refined INTENT	infotech	issue-core	finished	codex	infotech	2026-07-22	2026-07-22	08af499c-328f-53f8-8899-ae818fce048d

Implement connector alignment: mapping, docs hygiene, scope gaps vs refined INTENT

Origin

ISSUE-WP-0004 retargeted issue-core’s docs framing (connector, not landing zone) and produced a mapping design only. A follow-up audit (docs/intent-work-record-alignment-review.md) found no hard north-star collision with the work-record framework, but soft frictions (identity, diagram, dual lifecycles, shipped vs target). INTENT.md was rewritten 2026-07-22 to absorb those recommendations.

This workplan implements the refined intention against current SCOPE: the shipped product is still a pre-canon CRUD + TaskSpec shell; the work-record- aware connector (mapping, project/link, boundary-sync discipline, packaging hygiene) is not built. Cross-repo emitter policy remains ACTIVITY-WP-0022.

Goal

Close the gap between:

Layer	State at start of this WP
INTENT	Work-record-aligned connector (2026-07-22)
SCOPE §1 shipped	Models, SQLite/Gitea, CLI, REST TaskSpec, backend sync
SCOPE §1.8 / target	Mapping store/API, boundary sync, work_record_uuid, dual-lifecycle rules

Deliver a minimum viable connector core: durable mapping + project/link surface + schema extension + status-mapping policy + doc/package hygiene — without turning issue-core back into a work origin or fleet task board.

Non-goals

• Originating workplans/tasks/intake in this service.
• Replacing activity-core IssueSink policy implementation (track/coordinate ACTIVITY-WP-0022; do not duplicate).
• Full CRDT comment merge or multi-tracker fan-out.
• Auto-config from git remotes (ROADMAP Phase 1 — separate).
• GitHub/GitLab/Jira backends (unless a task explicitly needs a stub for mapping tests — prefer fake/local backend).

Dependencies

• INTENT.md + SCOPE.md (2026-07-21/22) + docs/uuid-external-id-mapping.md
• Work-record canon: the-custodian/canon/standards/work-record-types_v0.1.md
• Architecture §4.2
• activity-core ACTIVITY-WP-0022 (emitter default; may complete in parallel)
• Optional later: canon PR for work-record YAML back-reference field names

Tasks

Task: Freeze intent/scope cross-links and residual doc hygiene

id: ISSUE-WP-0005-T01
status: done
priority: high
state_hub_task_id: "024ae2f2-32c5-513f-a7b1-2cde1a1a141b"

Ensure INTENT, SCOPE, README “See also”, and the alignment review all point at the refined INTENT and this workplan. Update docs/intent-work-record- alignment-review.md with a short “Remediation” note (INTENT rewrite done; implementation tracked here). No new product claims.

Acceptance: Cross-links consistent; review file marks INTENT remediation done; no reintroduction of landing-zone language in those files.

Task: Packaging and capability framing cleanup

id: ISSUE-WP-0005-T02
status: done
priority: medium
state_hub_task_id: "e86786d7-0bd4-591c-87db-8780cc53d238"

Align packaging/metadata with connector intent (not “authoritative task lifecycle manager” / multi-agent coordination board):

• pyproject.toml description / keywords / long description if present
• registry/capabilities/capability.infotech.issue-tracking.md and CAPABILITY-issue-tracking.yaml discovery text
• AGENT_INTEGRATION.md intro + top-level guidance (prefer work records; use issue-core for external trackers)

Acceptance: Grep for “landing zone”, “tasks land”, “authoritative task lifecycle” in package/capability/agent docs is clean or historical-only; capability summary matches SCOPE §1 honesty.

Task: Specify dual-lifecycle and projection field rules (normative note)

id: ISSUE-WP-0005-T03
status: done
priority: high
state_hub_task_id: "cd4e298c-9a42-5d35-a8e3-40626f5a0fd8"

Turn INTENT’s boundary-sync discipline into an implementable policy doc under docs/ (e.g. docs/boundary-sync-and-status-mapping.md):

• Table: work-record task/intake/… status ↔ optional tracker IssueState (default: outward status projection rules; inward is suggest-only / no silent file write in v1)
• Fields that may project (title, body, agreed labels) vs stay on work record only (lane, tags policy, budgets, owner spine)
• Explicit: unmapped issues outside spine; mapping keys UUIDv7; canonical id for operator UX

Acceptance: Doc reviewed against work-record types standard; referenced from SCOPE §2 and mapping design; ready to drive T04–T06 without re-litigating policy.

Task: Implement mapping store (local SQLite)

id: ISSUE-WP-0005-T04
status: done
priority: high
state_hub_task_id: "027871b0-696d-5ab7-b18c-b26167e97813"

Per docs/uuid-external-id-mapping.md:

• Table work_record_issue_map (or equivalent) on local backend / dedicated store used even when CRUD backend is Gitea
• Uniqueness: active (backend, external_id) and active (work_record_uuid, backend)
• Domain service MappingService: upsert, resolve by UUID, by canonical id (if provided), by external id, detach
• Unit tests for idempotent project and uniqueness

Acceptance: Tests pass without a live Gitea; store survives reconnect; SCOPE §1.8 “mapping store” can move toward shipped with an honest partial note until CLI/API land.

Task: Project / link CLI (+ optional REST)

id: ISSUE-WP-0005-T05
status: done
priority: high
state_hub_task_id: "b9a18d1d-9b0b-5a5b-9b1f-c6cf89f6767a"

Ship operator surface:

• issue project <work_record_uuid|canonical-id> … — create external issue if needed, write mapping
• issue map link|show|detach … — link existing issue, resolve, detach
• Optional REST POST/GET /mappings/ if cheap once CLI works; otherwise CLI first and REST as follow-up task comment

Does not create work records. Creating an external issue without a work record remains existing issue create / POST /issues/ secondary path.

Acceptance: Documented in README/SCOPE; happy-path test with local backend; idempotent re-project returns existing mapping.

Task: Extend TaskSpec with optional work_record_uuid

id: ISSUE-WP-0005-T06
status: done
priority: medium
state_hub_task_id: "2a1f83ae-236a-588d-8127-deaff04b84a8"

• Add optional work_record_uuid (and optional work_record_id / work_record_kind) to TaskIngestionRequest
• On present UUID: create/reuse issue and upsert mapping (T04)
• Without UUID: current behavior (no mapping row)
• Keep triggering_event_id semantics unchanged (activity lineage)
• Tests for both paths; update SCOPE TaskSpec section

Acceptance: Backward-compatible OpenAPI/schema; documented; no requirement that emitters send UUID until ACTIVITY-WP-0022 / intentional project path uses it.

Task: Outward status projection (v1 boundary sync subset)

id: ISSUE-WP-0005-T07
status: done
priority: medium
state_hub_task_id: "e37e7f4a-ab35-52e3-929f-960dfde14348"

Implement outward-only application of T03 rules for mapped records (manual CLI trigger is enough for v1, e.g. issue map push-status):

• Given work-record status input (CLI flag or JSON), update external issue state per policy table
• Do not write work-record files
• Inward sync remains out of scope for this task (document as next)

Acceptance: Policy tests + one integration-style test on local/Gitea mock; SCOPE distinguishes backend sync vs work-record boundary sync clearly.

Task: SCOPE inventory refresh after implementation

id: ISSUE-WP-0005-T08
status: done
priority: medium
state_hub_task_id: "45fac55a-5000-51c5-96a8-920b3d1179d7"

After T04–T07, rewrite SCOPE §1 / §1.8 / §2 so shipped vs target matches reality (mapping store, CLI, TaskSpec fields, status push). Link T03 policy doc. Drop stale “design only” claims where implemented.

Acceptance: SCOPE §1 is again the honest inventory; no aspirational leakage into “shipped today.”

Task: Coordinate emitter side (activity-core) without implementing it here

id: ISSUE-WP-0005-T09
status: done
priority: low
state_hub_task_id: "4b0dd409-e23e-5e2f-9d6e-a3ae1664fb88"

• Confirm ACTIVITY-WP-0022 still covers default sink policy
• If needed, send a state-hub message or progress note linking ISSUE-WP-0005 mapping readiness to when intentional emits should pass work_record_uuid
• Do not implement activity-core changes in this repo

Acceptance: Cross-link noted in this workplan closure notes; no silent assumption that IssueSink is fixed.

Sequencing

T01 (docs links) ─┬─► T02 (packaging/capability)
                  └─► T03 (policy doc) ─► T04 (store) ─► T05 (CLI)
                                              └─► T06 (TaskSpec)
                                              └─► T07 (outward status)
                                                        └─► T08 (SCOPE refresh)
T09 anytime after T01 (coordination)

Acceptance (workplan)

• INTENT remains work-record-aligned; review remediation note closed
• Mapping store + project/link usable on local backend
• TaskSpec optional UUID path upserts mapping without breaking old clients
• Dual-lifecycle policy documented and used by outward push
• SCOPE inventory matches code
• Packaging/capability/agent docs no longer sell landing-zone coordination
• activity-core default sink still owned by ACTIVITY-WP-0022

See also

• INTENT.md (2026-07-22 rewrite)
• SCOPE.md
• docs/uuid-external-id-mapping.md
• docs/intent-work-record-alignment-review.md
• workplans/ISSUE-WP-0004-align-with-work-record-canon.md
• activity-core workplans/ACTIVITY-WP-0022-issuesink-no-default-forgejo.md
• the-custodian/canon/standards/work-record-types_v0.1.md