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

---
id: ISSUE-WP-0005
type: workplan
title: "Implement connector alignment: mapping, docs hygiene, scope gaps vs refined INTENT"
domain: infotech
repo: issue-core
status: finished
owner: codex
topic_slug: infotech
created: "2026-07-22"
updated: "2026-07-22"
state_hub_workstream_id: "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

```task
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

```task
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)

```task
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)

```task
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)

```task
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

```task
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)

```task
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

```task
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

```task
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

```text
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`