docs: declare institutional architecture boundary

AGENTS.md

@@ -0,0 +1,16 @@
+# GovOPlaN Policy Codex Guide
+
+## Scope
+
+This repository owns hierarchical policy evaluation, explicit overrides, provenance, simulation, and typed governance capabilities for consuming modules.
+
+## 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 Policy internals.
+- Maintain a static user/admin baseline and run `/mnt/DATA/git/govoplan/tools/checks/check-manifest-shapes.py` after behavior or manifest changes.
+
+## Boundaries
+
+- Policy returns explainable decisions; consuming modules enforce them and own business state.
+- Lower scopes may narrow inherited ceilings but must not silently loosen them.

src/govoplan_policy/backend/manifest.py

@@ -21,12 +21,14 @@ from govoplan_core.core.policy import (
     CAPABILITY_POLICY_VIEW_GOVERNANCE,
 )
 from govoplan_core.core.modules import (
+    DocumentationTopic,
     FrontendModule,
     MigrationSpec,
     ModuleContext,
     ModuleInterfaceProvider,
     ModuleManifest,
 )
+from govoplan_core.core.provider_governance import declared_module_architecture
 from govoplan_core.core.views import ViewSurface
 from govoplan_core.db.base import Base
 from govoplan_policy.backend.db import models as policy_models
@@ -118,6 +120,27 @@ manifest = ModuleManifest(
         ),
     ),
     route_factory=_route_factory,
+    documentation=(
+        DocumentationTopic(
+            id="policy.effective-decisions-and-provenance",
+            title="Understand effective policy decisions",
+            summary="Policy decisions explain whether an action is allowed, limited, inherited, or unavailable and identify the sources that produced the result.",
+            body="A lower scope may narrow an inherited ceiling but cannot silently loosen a stronger system or tenant rule. Consuming modules remain responsible for enforcing the returned decision and displaying its reason. Malformed explicit policy fails closed for the affected governed action rather than being treated as absent.",
+            documentation_types=("user",),
+            audience=("user", "tenant_admin", "policy_admin"),
+            metadata={"kind": "reference"},
+        ),
+        DocumentationTopic(
+            id="policy.hierarchy-overrides-and-retention",
+            title="Administer policy hierarchy and overrides",
+            summary="Policy evaluates versioned system, tenant, group, and user rules for retention and module-owned governed actions.",
+            body="Administrators can simulate effective retention before saving a lower-level change. Explicit overrides retain source and provenance information and are evaluated through typed capabilities for definitions, Views, function assignments, distribution channels, scheduling privacy, and retention. Templates and inherited definitions keep their upstream ceilings when reused or derived.",
+            documentation_types=("admin",),
+            audience=("policy_admin", "tenant_admin", "system_admin"),
+            related_modules=("dataflow", "workflow_engine", "views", "idm", "dist_lists", "scheduling"),
+            metadata={"kind": "reference"},
+        ),
+    ),
     migration_spec=MigrationSpec(
         module_id="policy",
         metadata=Base.metadata,
@@ -182,6 +205,18 @@ manifest = ModuleManifest(
         CAPABILITY_POLICY_PRIVACY_RETENTION: _privacy_retention_service,
         CAPABILITY_POLICY_SCHEDULING_PARTICIPANT_PRIVACY: _scheduling_participant_privacy_policy,
     },
+    architecture=declared_module_architecture(
+        layer="governance_accountability",
+        kind="governance",
+        maturity="vertical_slice",
+        documentation_ref="docs/POLICY_DECISION_PROVENANCE.md",
+        test_ref="tests/test_policy_hierarchy.py",
+        known_limits=("The current policy families do not yet form a universal expression or enforcement engine.",),
+        owned_concepts=("policy definition", "policy override", "policy decision provenance"),
+        non_owned_concepts=("application permission", "domain record", "audit record"),
+        recovery_docs=("docs/POLICY_DECISION_PROVENANCE.md",),
+        security_docs=("docs/POLICY_DECISION_PROVENANCE.md",),
+    ),
 )