From 3e9a14a9705d475f2b7de5281ec1661db64373bd Mon Sep 17 00:00:00 2001 From: Albrecht Degering Date: Sat, 1 Aug 2026 17:48:39 +0200 Subject: [PATCH] docs: declare institutional architecture boundary --- AGENTS.md | 16 +++++++++++ src/govoplan_scheduling/backend/manifest.py | 32 +++++++++++++++++++-- 2 files changed, 46 insertions(+), 2 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a08988f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# GovOPlaN Scheduling Codex Guide + +## Scope + +This repository owns poll-backed meeting scheduling, candidate slots, participants, constraints, availability, reminders, decisions, and Calendar handoff. + +## 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 Scheduling 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 + +- Poll owns reusable responses; Calendar owns events and free/busy; Notifications and Mail own delivery. +- Keep optional integrations capability-driven and preserve signed-link privacy and abuse controls. diff --git a/src/govoplan_scheduling/backend/manifest.py b/src/govoplan_scheduling/backend/manifest.py index 8ca2a07..50e39f7 100644 --- a/src/govoplan_scheduling/backend/manifest.py +++ b/src/govoplan_scheduling/backend/manifest.py @@ -19,6 +19,7 @@ from govoplan_core.core.modules import ( PublicFrontendRoute, RoleTemplate, ) +from govoplan_core.core.provider_governance import declared_module_architecture from govoplan_core.core.people import ( CAPABILITY_ACCESS_PEOPLE_SEARCH, CAPABILITY_ADDRESSES_PEOPLE_SEARCH, @@ -90,11 +91,26 @@ DOCUMENTATION = ( "flows remain possible." ), layer="available", - documentation_types=("admin",), - audience=("operator", "module_admin", "product_owner"), + documentation_types=("admin", "user"), + audience=("user", "operator", "module_admin", "product_owner"), related_modules=("poll", "evaluation", "calendar", "appointments", "mail", "notifications", "portal"), metadata={"seed": True}, ), + DocumentationTopic( + id="scheduling.find-and-decide-meeting-time", + title="Find and decide a meeting time", + summary="Create candidate slots, invite internal or external participants, compare availability, and turn the selected slot into a calendar event when Calendar is available.", + body=( + "Scheduling records participant requirements, quorum and weighting constraints, response deadlines, reminders, and yes/no/maybe availability through Poll. " + "Calendar-aware organizers can inspect conflicts and create tentative holds before deciding. After a decision, Scheduling releases unused holds, creates or links the final event, and records notification handoff state. " + "Signed external links expose only the bounded request information allowed by the request's participation and privacy policy." + ), + layer="configured", + documentation_types=("user",), + audience=("user", "organizer", "participant"), + related_modules=("poll", "calendar", "notifications", "mail"), + metadata={"kind": "reference"}, + ), ) @@ -225,6 +241,18 @@ manifest = ModuleManifest( ), ), documentation=DOCUMENTATION, + architecture=declared_module_architecture( + layer="communication_participation", + kind="domain", + maturity="vertical_slice", + documentation_ref="README.md", + test_ref="tests/test_service.py", + known_limits=("Reference deployment notification delivery and every calendar-provider constraint remain incomplete.",), + owned_concepts=("scheduling request", "candidate slot", "scheduling participant", "scheduling decision"), + non_owned_concepts=("poll response primitive", "calendar event", "mail delivery"), + recovery_docs=("README.md",), + security_docs=("README.md",), + ), )