feat: add search and external integration contracts

docs/EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md

@@ -0,0 +1,47 @@
+# External References And Integration Maturity
+
+GovOPlaN integrations use a shared external-reference contract instead of
+storing connector-specific URLs and identifiers in every module.
+
+An external reference identifies an object by:
+
+- external system instance
+- object type
+- stable external object ID
+- optional connector configuration
+- canonical HTTP(S) URL without embedded credentials
+- optional source version, ETag, observation time, and non-secret metadata
+
+The identity key is `system:object_type:object_id`. A GovOPlaN object may retain
+multiple references, but one reference must never silently change its identity.
+Moving or escalating work creates a new object and an explicit relationship; it
+does not rewrite either object's history.
+
+## Integration Maturity
+
+Maturity is cumulative:
+
+1. `discover`: identify configured external systems and their health.
+2. `link`: retain and open stable external references.
+3. `search`: include authorized external objects in GovOPlaN search.
+4. `read`: display authoritative external content.
+5. `publish`: create or update external content from GovOPlaN.
+6. `synchronize`: reconcile changes in both directions with conflict handling.
+7. `migrate`: perform a governed, verifiable transfer into GovOPlaN.
+8. `replace`: provide the native operational capability without the external tool.
+
+Connectors must declare and document the maturity they actually implement.
+`synchronize` requires durable cursors, idempotency, provenance, conflict
+handling, deletion semantics, and observable failures. A link-only connector
+must not imply that GovOPlaN holds an authoritative copy.
+
+## Domain Ownership
+
+- Domain modules own native GovOPlaN objects and their authorization.
+- Connectors own protocols, credentials, discovery, transport, and sync state.
+- Search owns indexing and result aggregation, but source modules remain
+  responsible for authorization.
+- Core owns only the stable DTOs and extension contracts.
+
+The Python contract is
+`govoplan_core.core.external_references.ExternalObjectReference`.

docs/GOVOPLAN_MASTER_ROADMAP.md

@@ -412,7 +412,7 @@ Goal: cover internal support and public issue reporting.
 
 Create or refine in this order:
 
-1. `govoplan-issue-reporting`: public/internal reports, categories, intake,
+1. `govoplan-tickets`: public/internal reports, requests, incidents, queues,
    location, evidence, and triage.
 2. `govoplan-helpdesk`: service desk tickets, queues, SLAs, assignments,
    escalation, and resolution evidence.

docs/PUBLIC_SECTOR_INTEGRATION_STRATEGY.md

@@ -5,6 +5,9 @@ before deciding to replace specialist workflows. This document is the core
 strategy index. The executable connector catalogue lives in
 `govoplan-connectors/docs/PUBLIC_SECTOR_INTEGRATION_CATALOGUE.md`.
 
+The canonical cumulative maturity model and external-object DTO are documented
+in [EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md](EXTERNAL_REFERENCES_AND_INTEGRATION_MATURITY.md).
+
 ## Strategy Labels
 
 Use one or more of these labels for every external system family: