diff --git a/AGENTS.md b/AGENTS.md index 557b91d..069098b 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/ORGANIZATION_MODEL.md b/docs/ORGANIZATION_MODEL.md index c478e2b..ff531f5 100644 --- a/docs/ORGANIZATION_MODEL.md +++ b/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 diff --git a/src/govoplan_organizations/backend/manifest.py b/src/govoplan_organizations/backend/manifest.py index e42234f..0259c86 100644 --- a/src/govoplan_organizations/backend/manifest.py +++ b/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("organizations:model:write", "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."), + _permission( + "organizations:model:read", + "View organization model", + "Read organization meta-model definitions such as unit types, structures, and relation types.", + ), + _permission( + "organizations:model:write", + "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),), - nav_items=(NavItem(path="/organizations", label="Organizations", icon="users", required_any=ORGANIZATIONS_READ_SCOPES, order=70),), + routes=( + 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: ( - _organization_directory - ), + CAPABILITY_ORGANIZATION_HIERARCHY_DIRECTORY: (_organization_directory), }, documentation=( DocumentationTopic( @@ -158,7 +223,8 @@ manifest = ModuleManifest( body=( "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." + "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",), + ), )