docs: align issue-core with work-record connector role (ISSUE-WP-0004)

Retarget INTENT, SCOPE, README, ROADMAP, and agent docs from "task landing
zone" to external-tracker connector per work-record canon and architecture
draft §4.2. Add UUID↔external-id mapping design; mark ISSUE-WP-0004 finished
and cross-file activity-core ACTIVITY-WP-0022 for IssueSink policy.

ROADMAP.md

@@ -1,8 +1,30 @@
 # Issue Core Roadmap
 
-**Long-term vision and implementation plan for agent-driven software development coordination.**
+**Long-term vision for issue-core as an external issue-tracker connector** —
+not as the fleet's work-origin or internal coordination substrate.
 
-## Current Status: v1.0 (Production-Ready Core)
+## Framing (updated 2026-07-20)
+
+Fleet coordination runs on **work records** (repo files + state-hub), per:
+
+- `the-custodian/canon/standards/work-record-types_v0.1.md`
+- `the-custodian/research/WorkOrchestrationArchitectureDraft.md` §4.2
+- `INTENT.md` / `SCOPE.md` / ISSUE-WP-0004
+
+issue-core's trajectory is therefore:
+
+1. **Keep** multi-backend CRUD, CLI, REST, and sync as a solid connector.
+2. **Add** durable **work-record UUID ↔ external issue id** mapping and
+   boundary sync (design: `docs/uuid-external-id-mapping.md`).
+3. **Stop** treating "everything lands in issue-core" as the product north star.
+   Agent claim/execute for *fleet* work belongs on work records; tracker
+   claim/locking remains useful for *external* issues.
+
+Phases below that talk about multi-agent coordination should be read as
+**coordination through an external tracker when one is in use**, not as
+replacing workplans/tasks.
+
+## Current Status: v1.0 (Production-Ready Connector Core)
 
 ✅ **Complete:**
 - Core CRUD operations (100%)
@@ -11,19 +33,40 @@
 - CLI with JSON output
 - Python programmatic API
 - Basic synchronization
-- Comprehensive test suite (109 tests, 61% coverage)
+- REST `POST/GET/PATCH /issues/` (intentional external issues)
+- Comprehensive test suite
 
 ⚠️ **Limitations:**
 - Manual backend configuration
 - No auto-detection
 - Basic conflict resolution
 - Hardcoded user context
+- No work-record UUID mapping yet (design only)
+- Docs historically framed issue-core as a landing zone (corrected in ISSUE-WP-0004)
 
 ---
 
-## Phase 1: Auto-Configuration (v1.1) - **Next Priority**
+## Phase 0: Work-record canon alignment (docs) — ISSUE-WP-0004
 
-**Goal:** Enable agents to work in any repository without manual setup.
+**Goal:** Align product framing with the connector decision; design mapping.
+
+| Item | Status |
+| --- | --- |
+| Rewrite INTENT.md | this workplan |
+| Rewrite SCOPE.md (mapping table concept) | this workplan |
+| README / ROADMAP framing | this workplan |
+| Design note: UUID ↔ external-id mapping | `docs/uuid-external-id-mapping.md` |
+| File activity-core IssueSink policy follow-up | cross-repo task |
+
+**Implementation of the mapping store is stage-3 in the-custodian work-record
+architecture — not blocked on inventing a parallel coordination system here.**
+
+---
+
+## Phase 1: Auto-Configuration (v1.1) - **Next engineering priority**
+
+**Goal:** Enable agents and operators to attach issue-core to any repo's
+external tracker without painful manual setup.
 
 ### 1.1.1 Git Remote Detection
 
@@ -245,9 +288,26 @@ fi
 
 ---
 
-## Phase 2: Agent Features (v1.2)
+## Phase 1.5: UUID ↔ external-id mapping (stage-3 work-record arch)
 
-**Goal:** Native support for multi-agent coordination.
+**Goal:** Persist and query the association between internal work-record
+UUIDs and backend issue ids so projections are first-class.
+
+See **`docs/uuid-external-id-mapping.md`** for the design (no code in
+ISSUE-WP-0004). Expected deliverables when scheduled:
+
+- Mapping table / store (local SQLite + optional remote annotation)
+- API/CLI: project work record → create or link external issue; resolve either way
+- Optional fields on `TaskSpec` / project request for `work_record_uuid`
+- Two-way status/comment sync *at the boundary* only when enabled
+- Idle cost zero when no mapping/integration is configured
+
+---
+
+## Phase 2: Agent Features for external trackers (v1.2)
+
+**Goal:** Native helpers when agents operate **on external issues** (not a
+replacement for work-record execution).
 
 ### 1.2.1 Agent Identity Management
 
@@ -473,9 +533,12 @@ issue webhook remove <id>
 
 ---
 
-## Phase 3: Advanced Coordination (v2.0)
+## Phase 3: Advanced tracker features (v2.0)
 
-**Goal:** Enterprise-grade multi-agent system coordination.
+**Goal:** Richer connector behavior for large external-tracker deployments
+(dependencies between *external* issues, query DSL, webhooks already partly
+in Phase 2). Fleet dependency graphs for work records remain out of scope
+here (workplan tooling / hub).
 
 ### 2.0.1 Issue Dependency Tracking
 
@@ -718,20 +781,30 @@ def sync_with_strategy(
 
 ## Success Metrics
 
+### Phase 0 Success (canon alignment)
+- [x] INTENT/SCOPE/README describe connector, not landing zone
+- [x] Mapping surface designed (`docs/uuid-external-id-mapping.md`)
+- [ ] activity-core IssueSink default no longer dumps internal findings to Forgejo
+
 ### Phase 1 Success
-- [ ] Agent can work in any repo with zero manual config
+- [ ] Agent can attach to any repo's tracker with zero manual config
 - [ ] Environment-only setup works: `GITEA_TOKEN=xxx issue list`
 - [ ] Auto-detection accuracy: >95% for common platforms
 
+### Phase 1.5 Success (mapping)
+- [ ] Project work-record UUID → external issue id is durable and queryable
+- [ ] Reverse lookup (external issue → UUID) works for linked issues
+- [ ] No mapping configured ⇒ no extra load / no accidental Forgejo spam
+
 ### Phase 2 Success
-- [ ] Multiple agents can coordinate without race conditions
-- [ ] Agent identity propagates to all operations
-- [ ] Claim/lock prevents concurrent work on same issue
+- [ ] Multiple agents can operate on external issues without race conditions
+- [ ] Agent identity propagates to tracker operations
+- [ ] Claim/lock prevents concurrent work on the same external issue
 
 ### Phase 3 Success
-- [ ] Complex dependency chains work correctly
-- [ ] Query DSL covers 90% of common queries
-- [ ] Real-time event processing with <1s latency
+- [ ] External-issue dependency helpers work where backends support them
+- [ ] Query DSL covers 90% of common tracker queries
+- [ ] Real-time tracker event processing with <1s latency when webhooks enabled
 
 ---