docs: declare institutional architecture boundary

AGENTS.md

@@ -1,5 +1,11 @@
 # GovOPlaN Organizations Codex Guide
 
+## Documentation Contract
+
+- Treat documentation as part of every behavior change. Update this module's manifest-driven `DocumentationTopic` contributions for affected user and administrator behavior.
+- Keep feature content here; `govoplan-docs` projects it without importing Organizations internals.
+- Maintain a static user/admin baseline and run `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` after behavior or manifest changes.
+
 ## Scope
 
 This repository owns the canonical GovOPlaN organizational model: tenant-local

docs/ORGANIZATION_MODEL.md

@@ -16,6 +16,13 @@ The organization model answers where responsibility lives.
 - Function: a named responsibility in an organization unit, such as clerk,
   reviewer, approver, committee secretary, intake desk, or resource manager.
 
+A function says what responsibility exists and where. It does not by itself
+prove that the institution or function is legally or organizationally
+competent for a subject, territory, population, decision type, signature, or
+period. That effective mandate/jurisdiction belongs to a separate shared
+Mandates contract. Organizations retains only stable references needed to
+explain how a mandate attaches to a unit or function.
+
 ## Governance And Templates
 
 Concrete organization models are tenant-owned. Units, structures, relation

src/govoplan_organizations/backend/manifest.py

@@ -2,7 +2,10 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from govoplan_core.core.access import CAPABILITY_AUTH_PERMISSION_EVALUATOR, CAPABILITY_AUTH_PRINCIPAL_RESOLVER
+from govoplan_core.core.access import (
+    CAPABILITY_AUTH_PERMISSION_EVALUATOR,
+    CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
+)
 from govoplan_core.core.module_guards import persistent_table_uninstall_guard
 from govoplan_core.core.modules import (
     DocumentationTopic,
@@ -16,6 +19,7 @@ from govoplan_core.core.modules import (
     PermissionDefinition,
     RoleTemplate,
 )
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.organizations import (
     CAPABILITY_ORGANIZATION_DIRECTORY,
     CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY,
@@ -48,14 +52,46 @@ def _permission(scope: str, label: str, description: str) -> PermissionDefinitio
 
 
 PERMISSIONS = (
-    _permission("organizations:model:read", "View organization model", "Read organization meta-model definitions such as unit types, structures, and relation types."),
+    _permission(
-    _permission("organizations:model:write", "Manage organization model", "Create and edit organization meta-model definitions."),
+        "organizations:model:read",
-    _permission("organizations:settings:read", "View organization settings", "Read organization governance, audit, and retention settings."),
+        "View organization model",
-    _permission("organizations:settings:write", "Manage organization settings", "Edit organization governance, audit, and retention settings."),
+        "Read organization meta-model definitions such as unit types, structures, and relation types.",
-    _permission("organizations:unit:read", "View organization units", "Read concrete organization units and relations."),
+    ),
-    _permission("organizations:unit:write", "Manage organization units", "Create and edit concrete organization units and relations."),
+    _permission(
-    _permission("organizations:function:read", "View organization functions", "Read function definitions."),
+        "organizations:model:write",
-    _permission("organizations:function:write", "Manage organization functions", "Create and edit function definitions."),
+        "Manage organization model",
+        "Create and edit organization meta-model definitions.",
+    ),
+    _permission(
+        "organizations:settings:read",
+        "View organization settings",
+        "Read organization governance, audit, and retention settings.",
+    ),
+    _permission(
+        "organizations:settings:write",
+        "Manage organization settings",
+        "Edit organization governance, audit, and retention settings.",
+    ),
+    _permission(
+        "organizations:unit:read",
+        "View organization units",
+        "Read concrete organization units and relations.",
+    ),
+    _permission(
+        "organizations:unit:write",
+        "Manage organization units",
+        "Create and edit concrete organization units and relations.",
+    ),
+    _permission(
+        "organizations:function:read",
+        "View organization functions",
+        "Read function definitions.",
+    ),
+    _permission(
+        "organizations:function:write",
+        "Manage organization functions",
+        "Create and edit function definitions.",
+    ),
 )
 
 ROLE_TEMPLATES = (
@@ -69,7 +105,12 @@ ROLE_TEMPLATES = (
         slug="organization_viewer",
         name="Organization viewer",
         description="Read organization model, organization units, and functions.",
-        permissions=("organizations:model:read", "organizations:settings:read", "organizations:unit:read", "organizations:function:read"),
+        permissions=(
+            "organizations:model:read",
+            "organizations:settings:read",
+            "organizations:unit:read",
+            "organizations:function:read",
+        ),
     ),
 )
 
@@ -92,7 +133,10 @@ manifest = ModuleManifest(
     id="organizations",
     name="Organizations",
     version="0.1.8",
-    required_capabilities=(CAPABILITY_AUTH_PRINCIPAL_RESOLVER, CAPABILITY_AUTH_PERMISSION_EVALUATOR),
+    required_capabilities=(
+        CAPABILITY_AUTH_PRINCIPAL_RESOLVER,
+        CAPABILITY_AUTH_PERMISSION_EVALUATOR,
+    ),
     optional_dependencies=("tenancy", "access", "audit", "policy"),
     provides_interfaces=(
         ModuleInterfaceProvider(
@@ -107,12 +151,35 @@ manifest = ModuleManifest(
     permissions=PERMISSIONS,
     role_templates=ROLE_TEMPLATES,
     route_factory=_route_factory,
-    nav_items=(NavItem(path="/organizations", label="Organizations", icon="users", required_any=ORGANIZATIONS_READ_SCOPES, order=70),),
+    nav_items=(
+        NavItem(
+            path="/organizations",
+            label="Organizations",
+            icon="users",
+            required_any=ORGANIZATIONS_READ_SCOPES,
+            order=70,
+        ),
+    ),
     frontend=FrontendModule(
         module_id="organizations",
         package_name="@govoplan/organizations-webui",
-        routes=(FrontendRoute(path="/organizations", component="OrganizationsPage", required_any=ORGANIZATIONS_READ_SCOPES, order=70),),
+        routes=(
-        nav_items=(NavItem(path="/organizations", label="Organizations", icon="users", required_any=ORGANIZATIONS_READ_SCOPES, order=70),),
+            FrontendRoute(
+                path="/organizations",
+                component="OrganizationsPage",
+                required_any=ORGANIZATIONS_READ_SCOPES,
+                order=70,
+            ),
+        ),
+        nav_items=(
+            NavItem(
+                path="/organizations",
+                label="Organizations",
+                icon="users",
+                required_any=ORGANIZATIONS_READ_SCOPES,
+                order=70,
+            ),
+        ),
         view_surfaces=(
             ViewSurface(
                 id="organizations.admin.tenant",
@@ -146,9 +213,7 @@ manifest = ModuleManifest(
     ),
     capability_factories={
         CAPABILITY_ORGANIZATION_DIRECTORY: _organization_directory,
-        CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (
+        CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (_organization_directory),
-            _organization_directory
-        ),
     },
     documentation=(
         DocumentationTopic(
@@ -159,6 +224,7 @@ manifest = ModuleManifest(
                 "Use organization unit types, structures, and relation types to model how the institution describes itself. "
                 "A concrete organization unit can participate in several structures at the same time, such as an employer hierarchy and an academic structure. "
                 "Functions describe responsibilities in organization units. IDM links identities to those functions, and Access maps accepted facts to roles and rights. "
+                "A function does not itself prove mandate, jurisdiction, decision authority, or signature authority; those effective institutional facts belong to a separate provider contract."
             ),
             layer="configured",
             documentation_types=("admin", "user"),
@@ -166,6 +232,18 @@ manifest = ModuleManifest(
             order=25,
         ),
     ),
+    architecture=declared_module_architecture(
+        layer="institutional_foundation",
+        kind="foundation",
+        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.",),
+        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",),
+        security_docs=("docs/ORGANIZATION_MODEL.md",),
+    ),
 )