--- 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 …` — 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`