Add governed organization template upgrades

src/govoplan_organizations/backend/manifest.py

@@ -189,6 +189,14 @@ manifest = ModuleManifest(
                 label="Organizations administration",
                 order=85,
             ),
+            ViewSurface(
+                id="organizations.admin.template-upgrades",
+                module_id="organizations",
+                kind="section",
+                label="Organization template upgrades",
+                parent_id="organizations.admin.tenant",
+                order=86,
+            ),
         ),
     ),
     migration_spec=MigrationSpec(
@@ -203,6 +211,7 @@ manifest = ModuleManifest(
             organization_models.OrganizationModelTemplate,
             organization_models.OrganizationModelTemplateVersion,
             organization_models.OrganizationModelInstantiation,
+            organization_models.OrganizationModelUpgrade,
             organization_models.OrganizationStructure,
             organization_models.OrganizationRelationType,
             organization_models.OrganizationRelation,
@@ -217,6 +226,53 @@ manifest = ModuleManifest(
         CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (_organization_directory),
     },
     documentation=(
+        DocumentationTopic(
+            id="organizations.template-upgrades",
+            title="Upgrade a tenant organization model",
+            summary=(
+                "Compare an immutable system template version with the current "
+                "tenant-owned model before explicitly applying an upgrade."
+            ),
+            body=(
+                "Open Organizations administration and create a preview for a newer "
+                "published version of the template used by the tenant. The persisted "
+                "three-way comparison separates compatible additions, compatible "
+                "changes, tenant-only divergence, destructive remapping, and invalid "
+                "references. Tenant-only changes are preserved. Conflicting or "
+                "destructive entries require an explicit keep, replace, or bounded "
+                "mapping decision. Applying the reviewed preview creates a new "
+                "tenant-owned instantiation and supersedes the previous provenance; "
+                "it never creates live inheritance. A stale preview is rejected if the "
+                "tenant model or either template version changed. Cancelling retains "
+                "the review record without modifying organization data."
+            ),
+            layer="configured",
+            documentation_types=("admin",),
+            audience=("tenant_admin", "operator"),
+            related_modules=("policy", "audit", "idm", "access"),
+            links=(
+                DocumentationLink(
+                    label="Organizations administration",
+                    href="/admin?section=tenant-organization-settings",
+                    kind="runtime",
+                ),
+                DocumentationLink(
+                    label="Organization upgrade API",
+                    href="/api/v1/organizations/model-upgrades",
+                    kind="api",
+                ),
+            ),
+            metadata={
+                "kind": "guide",
+                "help_contexts": [
+                    "organizations.admin.template-upgrades",
+                    "organizations.template-upgrade.preview",
+                    "organizations.template-upgrade.decision",
+                    "organizations.template-upgrade.apply",
+                ],
+            },
+            order=27,
+        ),
         DocumentationTopic(
             id="organizations.model",
             title="Organization model",
@@ -320,7 +376,9 @@ manifest = ModuleManifest(
         maturity="vertical_slice",
         documentation_ref="docs/ORGANIZATION_MODEL.md",
         test_ref="tests/test_model_templates.py",
-        known_limits=("Cross-tenant template lifecycle and target upgrade evidence are not reference-ready.",),
+        known_limits=(
+            "Downstream modules must reconcile organization-reference changes from the emitted upgrade event; cross-module records are not rewritten directly.",
+        ),
         owned_concepts=("organization unit", "organization structure", "organization relation", "organization function"),
         non_owned_concepts=("function incumbency", "identity", "application role", "mandate"),
         recovery_docs=("docs/ORGANIZATION_MODEL.md",),